From a42d372c2e4ad4ceba99264ab0b3d2a869a6a8a3 Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Mon, 14 Apr 2025 15:13:06 +0000 Subject: [PATCH 01/14] Update CLI docs for release 779/merge --- docs/cli/activity.mdx | 1078 +++++++++--- docs/cli/batch.mdx | 395 +++-- docs/cli/env.mdx | 520 +++++- docs/cli/operator.mdx | 2604 ++++++++++++++++++++++------ docs/cli/schedule.mdx | 1355 ++++++++++++--- docs/cli/server.mdx | 222 ++- docs/cli/task-queue.mdx | 2316 ++++++++++++++++++++++++- docs/cli/worker.mdx | 1217 +++++++++++++ docs/cli/workflow.mdx | 3609 ++++++++++++++++++++++++++++++++++----- 9 files changed, 11565 insertions(+), 1751 deletions(-) create mode 100644 docs/cli/worker.mdx diff --git a/docs/cli/activity.mdx b/docs/cli/activity.mdx index 66aec7c224..aa376e76cc 100644 --- a/docs/cli/activity.mdx +++ b/docs/cli/activity.mdx @@ -1,311 +1,961 @@ --- id: activity -title: Temporal CLI activity command reference -sidebar_label: activity +title: temporal activity +sidebar_label: temporal activity description: Learn how to use Temporal Activity commands for completing or failing Activity Executions in your Workflow. Optimize your Temporal Workflow management effectively. toc_max_heading_level: 4 keywords: - activity - activity complete - - activity execution - - activity fail - activity update-options - activity pause - activity unpause - activity reset + - activity execution + - activity fail - cli reference - cli-feature - command-line-interface-cli - temporal cli tags: - - Activities - - Temporal CLI + - activity + - activity-complete + - activity-update-options + - activity-pause + - activity-unpause + - activity-reset + - activity-execution + - activity-fail + - cli-reference + - cli-feature + - command-line-interface-cli + - temporal-cli --- -# Temporal CLI activity command reference +## complete -Activity commands operate on [Activity Executions](/activity-execution). +Complete an Activity, marking it as successfully finished. Specify the +Activity ID and include a JSON result for the returned value: -Activity commands follow this syntax: -`temporal activity [command] [command options]` +``` +temporal activity complete \ + --activity-id YourActivityId \ + --workflow-id YourWorkflowId \ + --result '{"YourResultKey": "YourResultVal"}' +``` -## complete +Use the following options to change the behavior of this command. -The `temporal activity complete` command completes an [Activity Execution](/activity-execution). -Along with completing the Activity, the result given upon return can be set as well. +**Flags:** -`temporal activity complete --activity-id=MyActivity --result=ActivityComplete` +**--activity-id** _string_ -Use the following options to change the behavior of this command. +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. + +**--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. + +**--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") + +**--time-format** _string-enum_ -- [--activity-id](/cli/cmd-options#activity-id) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--address](/cli/cmd-options#address) +**--tls** _bool_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--tls-ca-data** _string_ -- [--color](/cli/cmd-options#color) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--tls-ca-path** _string_ -- [--env](/cli/cmd-options#env) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--tls-cert-data** _string_ -- [--identity](/cli/cmd-options#identity) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--namespace](/cli/cmd-options#namespace) +**--tls-cert-path** _string_ -- [--result](/cli/cmd-options#result) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--run-id](/cli/cmd-options#run-id) +**--tls-disable-host-verification** _bool_ -- [--tls](/cli/cmd-options#tls) +Disable TLS host-name verification. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--tls-key-data** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls-key-path** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--tls-server-name** _string_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Override target TLS server name. ## fail -The `temporal activity fail` command fails an [Activity Execution](/activity-execution). -The Activity must already be running on a valid [Workflow](/workflows). +Fail an Activity, marking it as having encountered an error. Specify the +Activity and Workflow IDs: -`temporal fail --workflow-id=meaningful-business-id --activity-id=MyActivity` +``` +temporal activity fail \ + --activity-id YourActivityId \ + --workflow-id YourWorkflowId +``` Use the following options to change the behavior of this command. -- [--activity-id](/cli/cmd-options#activity-id) +**Flags:** -- [--address](/cli/cmd-options#address) +**--activity-id** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Activity ID to fail. Required. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--detail** _string_ -- [--color](/cli/cmd-options#color) +Reason for failing the Activity (JSON). -- [--command-timeout](/cli/cmd-options#command-timeout) +**--identity** _string_ -- [--detail](/cli/cmd-options#detail) +Identity of the user submitting this request. -- [--env](/cli/cmd-options#env) +**--reason** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Reason for failing the Activity. -- [--identity](/cli/cmd-options#identity) +**Global Flags:** -- [--namespace](/cli/cmd-options#namespace) +**--address** _string_ -- [--reason](/cli/cmd-options#reason) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--run-id](/cli/cmd-options#run-id) +**--api-key** _string_ -- [--tls](/cli/cmd-options#tls) +API key for request. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--codec-auth** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Authorization header for Codec Server requests. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--codec-endpoint** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Remote Codec Server endpoint. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--codec-header** _string[]_ -- [--workflow-id](/cli/cmd-options#workflow-id) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -## update-options +**--color** _string-enum_ -The `temporal activity update-options` command lets you fix running Activities by updating the options that were passed in by the Activity's Parent Workflow. +Output coloring. Accepted values: always, never, auto. (default "auto") -The Activity must already be running on a valid [Workflow](/workflows). -Updates are incremental, only changing the specified options. Either the Activity Id or Activity Type must be provided. -If Activity Type is provided, and there are multiple pending Activities of the provided type, then all of them will be updated. -The command will return the new Activity options for an [Activity Execution](/activity-execution). +**--command-timeout** _duration_ -Use the following options to change the behavior of this command. +The command execution timeout. 0s means no timeout. + +**--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. + +**--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") + +**--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. + +**--tls-ca-data** _string_ -Routing options: -- [--activity-id](/cli/cmd-options#activity-id) -- [--activity-type](/cli/cmd-options#activity-type) -- [--workflow-id](/cli/cmd-options#workflow-id) -- [--run-id](/cli/cmd-options#run-id) -- [--namespace](/cli/cmd-options#namespace) - - -You can update the following Activity options: - -- [--task-queue](/cli/cmd-options#task-queue) -- [--schedule-to-close-timeout](/cli/cmd-options#schedule-to-close-timeout) -- [--schedule-to-start-timeout](/cli/cmd-options#schedule-to-start-timeout) -- [--start-to-close-timeout](/cli/cmd-options#start-to-close-timeout) -- [--heartbeat-timeout](/cli/cmd-options#heartbeat-timeout) -- [--retry-initial-interval](/cli/cmd-options#retry-initial-interval) -- [--retry-maximum-interval](/cli/cmd-options#retry-maximum-interval) -- [--retry-backoff-coefficient](/cli/cmd-options#retry-backoff-coefficient) -- [--retry-maximum-attempts](/cli/cmd-options#retry-maximum-attempts) - -Other options: -- [--identity](/cli/cmd-options#identity) -- [--tls](/cli/cmd-options#tls) -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) -- [--tls-key-path](/cli/cmd-options#tls-key-path) -- [--tls-server-name](/cli/cmd-options#tls-server-name) -- [--address](/cli/cmd-options#address) -- [--codec-auth](/cli/cmd-options#codec-auth) -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) -- [--color](/cli/cmd-options#color) -- [--command-timeout](/cli/cmd-options#command-timeout) -- [--detail](/cli/cmd-options#detail) -- [--env](/cli/cmd-options#env) -- [--grpc-meta](/cli/cmd-options#grpc-meta) +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 -The `temporal activity pause` command pauses an [Activity Execution](/activity-execution) specified by its ID or type. -Pausing the Activity can be undone by using the `temporal activity unpause` command. +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 to completion. +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 can be specified by their Activity ID or Activity Type. +One of those parameters must be provided. If both are provided - Activity +Type will be used, and Activity ID will be ignored. + +``` + +Specify the Activity and Workflow IDs: + +``` +temporal activity pause \ + --activity-id YourActivityId \ + --workflow-id YourWorkflowId +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--activity-id**, **-a** _string_ + +Activity ID to pause. + +**--activity-type**, **-g** _string_ + +Activity Type to pause. + +**--identity** _string_ + +Identity of the user submitting this request. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. -Pausing an Activity means: -* If the Activity is currently waiting for a retry or is running and subsequently fails, it will not be rescheduled until it is unpaused. -* If the Activity is already paused, calling this method will have no effect. -* If the Activity is running and finishes successfully, the Activity will be completed. -* If the Activity is running and finishes with failure: - * If no retries remain, the Activity will be completed. - * If retries remain, the Activity will be paused. +**--tls-cert-path** _string_ -If Activity Type is provided and multiple pending Activities of the provided type exist, all of them will be paused. +Path to x509 certificate. Can't be used with --tls-cert-data. -For long-running Activities, Activities in a paused state will send a cancellation with `activity_paused` set to `true` as a part of [Activity Heartbeat](/encyclopedia/detecting-activity-failures#activity-heartbeat) response. -You can choose how you would like to handle this case in your Activity. +**--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 + +Resetting an activity resets both the number of attempts and the activity +timeout. + +If activity is paused and 'keep_paused' flag is not provided - it will be +unpaused. +If activity is paused and 'keep_paused' flag is provided - it will stay +paused. +If activity is waiting for the retry, is will be rescheduled immediately. +If the 'reset_heartbeats' flag is set, the activity heartbeat timer and +heartbeats will be reset. + +Activities can be specified by their Activity ID or Activity Type. +One of those parameters must be provided. If both are provided - Activity +Type will be used, and Activity ID will be ignored. + +Specify the Activity Type of ID and Workflow IDs: + +``` +temporal activity reset \ + --activity-id YourActivityId \ + --workflow-id YourWorkflowId + --keep-paused + --reset-heartbeats +``` -This command returns a `NotFound` error if there is no pending Activity with the provided ID or type. Use the following options to change the behavior of this command. -Routing options: -- [--activity-id](/cli/cmd-options#activity-id) -- [--activity-type](/cli/cmd-options#activity-type) -- [--workflow-id](/cli/cmd-options#workflow-id) -- [--run-id](/cli/cmd-options#run-id) -- [--namespace](/cli/cmd-options#namespace) - -Other options: - - [--identity](/cli/cmd-options#identity) - - [--tls](/cli/cmd-options#tls) - - [--tls-ca-path](/cli/cmd-options#tls-ca-path) - - [--tls-cert-path](/cli/cmd-options#tls-cert-path) - - [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) - - [--tls-key-path](/cli/cmd-options#tls-key-path) - - [--tls-server-name](/cli/cmd-options#tls-server-name) - - [--address](/cli/cmd-options#address) - - [--codec-auth](/cli/cmd-options#codec-auth) - - [--codec-endpoint](/cli/cmd-options#codec-endpoint) - - [--color](/cli/cmd-options#color) - - [--command-timeout](/cli/cmd-options#command-timeout) - - [--detail](/cli/cmd-options#detail) - - [--env](/cli/cmd-options#env) - - [--grpc-meta](/cli/cmd-options#grpc-meta) +**Flags:** + +**--activity-id**, **-a** _string_ + +Activity ID to pause. + +**--activity-type**, **-g** _string_ + +Activity Type to pause. + +**--identity** _string_ + +Identity of the user submitting this request. + +**--keep-paused** _bool_ + +If activity was paused - it will stay paused. + +**--reset-heartbeats** _bool_ + +Reset the Activity's heartbeat. + +**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. + +**--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. + +**--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") + +**--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. + +**--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 -The `temporal activity unpause` command unpauses an [Activity Execution](/activity-execution) specified by its ID or type. -If there are multiple pending Activities of the provided type, then all of them will be unpaused. -If Activity is not paused, this call will have no effect. -If the Activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag). -Once the Activity is unpaused, all Timeout timers will be regenerated. +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. -Command will fail with a `NotFound` error if there is no pending Activity with the provided ID or type. +Activities can be specified by their Activity ID or Activity Type. +One of those parameters must be provided. If both are provided - Activity +Type will be used, and Activity ID will be ignored. Activities can be unpaused in bulk via a visibility Query list filter: ``` -temporal activity unpause --query YourQuery \ - --reason YourReasonForUnpause +temporal activity unpause \ + --query YourQuery \ + --reason YourReasonForTermination ``` -Routing options: -- [--activity-id](/cli/cmd-options#activity-id) -- [--activity-type](/cli/cmd-options#activity-type) -- [--workflow-id](/cli/cmd-options#workflow-id) -- [--run-id](/cli/cmd-options#run-id) -- [--namespace](/cli/cmd-options#namespace) - -Unpause specific options: -- [--match-all](/cli/cmd-options#match-all) -- [--reset-attempts](/cli/cmd-options#reset-attempts) -- [--reset-heartbeat](/cli/cmd-options#reset-heartbeat) -- [--jitter](/cli/cmd-options#activity-jitter) - -Other options: - - [--identity](/cli/cmd-options#identity) - - [--tls](/cli/cmd-options#tls) - - [--tls-ca-path](/cli/cmd-options#tls-ca-path) - - [--tls-cert-path](/cli/cmd-options#tls-cert-path) - - [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) - - [--tls-key-path](/cli/cmd-options#tls-key-path) - - [--tls-server-name](/cli/cmd-options#tls-server-name) - - [--address](/cli/cmd-options#address) - - [--codec-auth](/cli/cmd-options#codec-auth) - - [--codec-endpoint](/cli/cmd-options#codec-endpoint) - - [--color](/cli/cmd-options#color) - - [--command-timeout](/cli/cmd-options#command-timeout) - - [--detail](/cli/cmd-options#detail) - - [--env](/cli/cmd-options#env) - - [--grpc-meta](/cli/cmd-options#grpc-meta) +Specify the Activity ID or Type and Workflow IDs: -## reset +``` +temporal activity unpause \ + --activity-id YourActivityId \ + --workflow-id YourWorkflowId + --reset-attempts + --reset-heartbeats +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--activity-id**, **-a** _string_ + +Activity ID to unpause. Can only be used without --query. + +**--activity-type**, **-g** _string_ + +Activity Type to unpause. + +**--identity** _string_ + +Identity of the user 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. + +**--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. + +**--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") + +**--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. + +**--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 + +Update Activity options. Specify the Activity and Workflow IDs, and +options you want to update. +Updates are incremental, only changing the specified options. + +``` +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 + +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--activity-id** _string_ + +Activity ID. Required. + +**--heartbeat-timeout** _duration_ + +Maximum permitted time between successful worker heartbeats. + +**--identity** _string_ + +Identity of the user submitting this request. + +**--retry-backoff-coefficient** _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** _duration_ + +Interval of the first retry. If retryBackoffCoefficient is 1.0 then it is used for all retries. + +**--retry-maximum-attempts** _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** _duration_ + +Maximum interval between retries. Exponential backoff leads to interval increase. This value is the cap of the increase. + +**--schedule-to-close-timeout** _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** _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** _duration_ + +Maximum time an activity is allowed to execute after being picked up by a worker. This timeout is always retryable. + +**--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. + +**--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. + +**--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") + +**--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. + +**--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_ -The `temporal activity reset` command restarts a running [Activity Execution](/activity-execution) specified by its ID or type. -If there are multiple pending activities of the provided type - all of them will be reset. -Resetting an Activity means: -* The number of attempts will be reset to 0; -* Activity timeouts will be reset; -* If the Activity is waiting for retry, it will be scheduled immediately (* see 'jitter' flag); -* If the Activity is currently executing, it will be reset once/if it completes with failure; -* If the Activity is paused, it will be unpaused. If you want it to stay paused, you can pass --keep-paused flag; - -Command will fail with a `NotFound` error if there is no pending Activity with the provided ID or type. -This may happen if the Activity has already completed. - -Routing options: -- [--activity-id](/cli/cmd-options#activity-id) -- [--activity-type](/cli/cmd-options#activity-type) -- [--workflow-id](/cli/cmd-options#workflow-id) -- [--run-id](/cli/cmd-options#run-id) -- [--namespace](/cli/cmd-options#namespace) - -Reset specific options: -- [--keep-paused](/cli/cmd-options#keep-paused) -- [--reset-heartbeat](/cli/cmd-options#reset-heartbeat) -- [--jitter](/cli/cmd-options#activity-jitter) - -Other options: - - [--identity](/cli/cmd-options#identity) - - [--tls](/cli/cmd-options#tls) - - [--tls-ca-path](/cli/cmd-options#tls-ca-path) - - [--tls-cert-path](/cli/cmd-options#tls-cert-path) - - [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) - - [--tls-key-path](/cli/cmd-options#tls-key-path) - - [--tls-server-name](/cli/cmd-options#tls-server-name) - - [--address](/cli/cmd-options#address) - - [--codec-auth](/cli/cmd-options#codec-auth) - - [--codec-endpoint](/cli/cmd-options#codec-endpoint) - - [--color](/cli/cmd-options#color) - - [--command-timeout](/cli/cmd-options#command-timeout) - - [--detail](/cli/cmd-options#detail) - - [--env](/cli/cmd-options#env) - - [--grpc-meta](/cli/cmd-options#grpc-meta) +Override target TLS server name. diff --git a/docs/cli/batch.mdx b/docs/cli/batch.mdx index dbf6a830f7..6d31a13639 100644 --- a/docs/cli/batch.mdx +++ b/docs/cli/batch.mdx @@ -1,7 +1,7 @@ --- id: batch -title: Temporal CLI batch command reference -sidebar_label: batch +title: temporal batch +sidebar_label: temporal batch description: Use Temporal CLI to manage multiple Workflow Executions with Batch Jobs that can Cancel, Signal, or Terminate Workflows. Filter and monitor Batch Jobs effectively. toc_max_heading_level: 4 keywords: @@ -14,190 +14,379 @@ keywords: - command-line-interface-cli - temporal cli tags: - - Temporal CLI + - batch + - batch-describe + - batch-list + - batch-terminate + - cli-reference + - cli-feature + - command-line-interface-cli + - temporal-cli --- -Batch commands change multiple [Workflow Executions](/workflow-execution) by providing a [List Filter](/temporal-service/visibility) and the type of Batch Job to execute. -The List Filter identifies the Workflow Executions in the Batch Job; the Batch type determines what will happen to the Workflow Executions. +## describe + +Show the progress of an ongoing batch job. Pass a valid job ID to display its +information: + +``` +temporal batch describe \ + --job-id YourJobId +``` + +Use the following options to change the behavior of this command. -**Which batch operations can be performed by the Temporal CLI?** +**Flags:** -There are three types of Batch Jobs: +**--job-id** _string_ -- Cancel: cancels the Workflow Executions specified by the List Filter. -- Signal: sends a [Signal](/sending-messages#sending-signals) to the Workflow Executions specified by the List Filter. -- Terminate: terminates the Workflow Executions specified by the List Filter. +Batch job ID. Required. -Batch operations can affect multiple Workflows simultaneously. -Depending on your needs, you might want to send Signals to running Workflows, Cancel them, or even Terminate them entirely. -Below are examples of how to use the Temporal CLI for each type of Batch operation. +**Global Flags:** -These commands will directly impact the Workflows you target, so it's important to use them judiciously. +**--address** _string_ -You can use the `--query` flag, which acts as [List Filter](/list-filter), to filter the Workflow Executions to be affected by the Batch Job. +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -To Cancel Workflows: +**--api-key** _string_ -```command -temporal workflow cancel \ - --query 'ExecutionStatus = "Running" AND WorkflowType="YourWorkflow"' \ - --reason "Testing" -``` +API key for request. -To Signal Workflows: +**--codec-auth** _string_ -```command -temporal workflow signal \ - --workflow-id MyWorkflowId \ - --name MySignal \ - --input '{"Input": "As-JSON"}' \ - --query 'ExecutionStatus = "Running" AND WorkflowType="YourWorkflow"' \ - --reason "Testing" -``` +Authorization header for Codec Server requests. -To Terminate Workflows: +**--codec-endpoint** _string_ -```command -temporal workflow terminate \ - --query 'ExecutionStatus = "Running" AND WorkflowType="YourWorkflow"' \ - --reason "Testing" -``` +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. + +**--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. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ -A successfully started Batch job will return a Job ID. -Use this Job ID to execute other actions on the Batch job. +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") + +**--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. + +**--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. ## list -The `temporal batch list` command returns all Batch jobs. -Batch Jobs can be returned for an entire Cluster or a single Namespace. +Return a list of batch jobs on the Service or within a single Namespace. For +example, list the batch jobs for "YourNamespace": -`temporal batch list --namespace=MyNamespace` +``` +temporal batch list \ + --namespace YourNamespace +``` Use the following options to change the behavior of this command. -- [--address](/cli/cmd-options#address) +**Flags:** -- [--codec-auth](/cli/cmd-options#codec-auth) +**--limit** _int_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Maximum number of batch jobs to display. -- [--color](/cli/cmd-options#color) +**Global Flags:** -- [--command-timeout](/cli/cmd-options#command-timeout) +**--address** _string_ -- [--env](/cli/cmd-options#env) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--fields](/cli/cmd-options#fields) +**--api-key** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +API key for request. -- [--limit](/cli/cmd-options#limit) +**--codec-auth** _string_ -- [--namespace](/cli/cmd-options#namespace) +Authorization header for Codec Server requests. -- [--no-pager](/cli/cmd-options#no-pager) +**--codec-endpoint** _string_ -- [--output](/cli/cmd-options#output) +Remote Codec Server endpoint. -- [--pager](/cli/cmd-options#pager) +**--codec-header** _string[]_ -- [--time-format](/cli/cmd-options#time-format) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls](/cli/cmd-options#tls) +**--color** _string-enum_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--command-timeout** _duration_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +The command execution timeout. 0s means no timeout. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--env** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Active environment name (`ENV`). (default "default") -## describe +**--env-file** _string_ -The `temporal batch describe` command shows the progress of an ongoing Batch job. +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -Pass a valid Job ID to return a Batch Job's information. +**--grpc-meta** _string[]_ -`temporal batch describe --job-id=MyJobId` +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -Use the following options to change the behavior of this command. +**--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") -- [--address](/cli/cmd-options#address) +**--no-json-shorthand-payloads** _bool_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Raw payload output, even if the JSON option was used. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--output**, **-o** _string-enum_ -- [--color](/cli/cmd-options#color) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--command-timeout](/cli/cmd-options#command-timeout) +**--time-format** _string-enum_ -- [--env](/cli/cmd-options#env) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--fields](/cli/cmd-options#fields) +**--tls** _bool_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--job-id](/cli/cmd-options#job-id) +**--tls-ca-data** _string_ -- [--namespace](/cli/cmd-options#namespace) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--output](/cli/cmd-options#output) +**--tls-ca-path** _string_ -- [--time-format](/cli/cmd-options#time-format) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--tls](/cli/cmd-options#tls) +**--tls-cert-data** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--tls-cert-path** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--tls-disable-host-verification** _bool_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +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. ## terminate -The `temporal batch terminate` command terminates a Batch job with the provided Job ID. -For future reference, provide a reason for terminating the Batch Job. +Terminate a batch job with the provided job ID. You must provide a reason for +the termination. The Service stores this explanation as metadata for the +termination event for later reference: -`temporal batch terminate --job-id=MyJobId --reason=JobReason` +``` +temporal batch terminate \ + --job-id YourJobId \ + --reason YourTerminationReason +``` Use the following options to change the behavior of this command. -- [--address](/cli/cmd-options#address) +**Flags:** + +**--job-id** _string_ + +Job ID to terminate. Required. + +**--reason** _string_ + +Reason for terminating the batch job. 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. + +**--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. + +**--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") + +**--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. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--tls-ca-path** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--color](/cli/cmd-options#color) +**--tls-cert-data** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--env](/cli/cmd-options#env) +**--tls-cert-path** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--job-id](/cli/cmd-options#job-id) +**--tls-disable-host-verification** _bool_ -- [--namespace](/cli/cmd-options#namespace) +Disable TLS host-name verification. -- [--reason](/cli/cmd-options#reason) +**--tls-key-data** _string_ -- [--tls](/cli/cmd-options#tls) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--tls-key-path** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls-server-name** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Override target TLS server name. -- [--tls-server-name](/cli/cmd-options#tls-server-name) diff --git a/docs/cli/env.mdx b/docs/cli/env.mdx index 8be0319830..3b7daf1423 100644 --- a/docs/cli/env.mdx +++ b/docs/cli/env.mdx @@ -1,7 +1,7 @@ --- id: env -title: Temporal CLI env command reference -sidebar_label: env +title: temporal env +sidebar_label: temporal env description: Temporal CLI 'env' commands allow the configuration, setting, deleting, and listing of environmental properties, making it easy to manage Temporal Server instances. toc_max_heading_level: 4 keywords: @@ -16,165 +16,517 @@ keywords: - environment - temporal cli tags: - - Temporal CLI + - cli-reference + - command-line-interface-cli + - configuration + - env + - env-delete + - env-get + - env-list + - env-set + - environment + - temporal-cli --- -Environment (or 'env') commands let the user configure the properties for the environment in use. +## delete + +Remove a presets environment entirely _or_ remove a key-value pair within an +environment. If you don't specify an environment (with `--env` or by setting +the `TEMPORAL_ENV` variable), this command updates the "default" environment: + +``` +temporal env delete \ + --env YourEnvironment +``` + +or + +``` +temporal env delete \ + --env prod \ + --key tls-key-path +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--key**, **-k** _string_ + +Property name. + +**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. + +**--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. + +**--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_ -Use `env ` alongside other commands to point the Temporal CLI at a different Temporal Server instance. +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--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. + +**--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. ## get -The `temporal env get` command prints the environmental properties for the environment in use. +List the properties for a given environment: -For example, passing the 'local' [Namespace](/namespaces) returns the name, address, and certificate paths for the local environment. -`temporal env get local` -`Output: tls-cert-path /home/my-user/certs/cluster.cert tls-key-path /home/my-user/certs/cluster.key address 127.0.0.1:7233 namespace accounting` +``` +temporal env get \ + --env YourEnvironment +``` -Output can be narrowed down to a specific option. -`temporal env get local.tls-key-path` -`tls-key-path /home/my-user/certs/cluster.key` +Print a single property: -Use the following options to change the command's behavior. +``` +temporal env get \ + --env YourEnvironment \ + --key YourPropertyKey +``` -- [--address](/cli/cmd-options#address) +If you don't specify an environment (with `--env` or by setting the +`TEMPORAL_ENV` variable), this command lists properties of the "default" +environment. -- [--codec-auth](/cli/cmd-options#codec-auth) +Use the following options to change the behavior of this command. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**Flags:** -- [--color](/cli/cmd-options#color) +**--key**, **-k** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Property name. -- [--env](/cli/cmd-options#env) +**Global Flags:** -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--address** _string_ -- [--namespace](/cli/cmd-options#namespace) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--tls](/cli/cmd-options#tls) +**--api-key** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +API key for request. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--codec-auth** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Authorization header for Codec Server requests. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--codec-endpoint** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Remote Codec Server endpoint. -## set +**--codec-header** _string[]_ -The `temporal env set` command sets the value for an environmental property. -Property names match CLI option names. +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -`temporal env set prod.tls-cert-path /home/my-user/certs/cluster.cert` +**--color** _string-enum_ -Properties can be set for the entire system, such as the frontend address: -`temporal env set local.address 127.0.0.1:7233` +Output coloring. Accepted values: always, never, auto. (default "auto") -Use the following options to change the command's behavior. +**--command-timeout** _duration_ -- [--address](/cli/cmd-options#address) +The command execution timeout. 0s means no timeout. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--env** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Active environment name (`ENV`). (default "default") -- [--color](/cli/cmd-options#color) +**--env-file** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--env](/cli/cmd-options#env) +**--grpc-meta** _string[]_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--namespace](/cli/cmd-options#namespace) +**--log-format** _string-enum_ -- [--tls](/cli/cmd-options#tls) +Log format. Accepted values: text, json. (default "text") -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--log-level** _string-enum_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--namespace**, **-n** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Temporal Service Namespace. (default "default") -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--no-json-shorthand-payloads** _bool_ -## delete +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") -The `temporal env delete` command deletes a given environment or environmental property. +**--time-format** _string-enum_ -`temporal env delete [environment or property]` +Time format. Accepted values: relative, iso, raw. (default "relative") -Pass a valid [Namespace](/namespaces) into the command to delete an environment and its saved values. +**--tls** _bool_ -`temporal env delete local` +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -Use the following options to change the command's behavior. +**--tls-ca-data** _string_ -- [--address](/cli/cmd-options#address) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--tls-ca-path** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--color](/cli/cmd-options#color) +**--tls-cert-data** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--env](/cli/cmd-options#env) +**--tls-cert-path** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--namespace](/cli/cmd-options#namespace) +**--tls-disable-host-verification** _bool_ -- [--tls](/cli/cmd-options#tls) +Disable TLS host-name verification. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--tls-key-data** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls-key-path** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--tls-server-name** _string_ + +Override target TLS server name. ## list -List all environments. +List the environments you have set up on your local computer. Environments are +stored in "$HOME/.config/temporalio/temporal.yaml". + +Use the following options to change the behavior of this command. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +## set + +Assign a value to a property key and store it to an environment: + +``` +temporal env set \ + --env environment \ + --key property \ + --value value +``` + +If you don't specify an environment (with `--env` or by setting the +`TEMPORAL_ENV` variable), this command sets properties in the "default" +environment. + +Storing keys with CLI option names lets the CLI automatically set those +options for you. This reduces effort and helps avoid typos when issuing +commands. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--key**, **-k** _string_ + +Property name (required). + +**--value**, **-v** _string_ + +Property value (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. + +**--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. + +**--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") + +**--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. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--address](/cli/cmd-options#address) +**--tls-ca-path** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--tls-cert-data** _string_ -- [--color](/cli/cmd-options#color) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--tls-cert-path** _string_ -- [--env](/cli/cmd-options#env) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--tls-disable-host-verification** _bool_ -- [--namespace](/cli/cmd-options#namespace) +Disable TLS host-name verification. -- [--output](/cli/cmd-options#output) +**--tls-key-data** _string_ -- [--tls](/cli/cmd-options#tls) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--tls-key-path** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls-server-name** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Override target TLS server name. -- [--tls-server-name](/cli/cmd-options#tls-server-name) diff --git a/docs/cli/operator.mdx b/docs/cli/operator.mdx index a013c50977..93c9d6a542 100644 --- a/docs/cli/operator.mdx +++ b/docs/cli/operator.mdx @@ -1,8 +1,8 @@ --- id: operator -title: Temporal CLI operator command reference -sidebar_label: operator -description: Operator commands in Temporal allow actions on Namespaces, Search Attributes, and Clusters using specific subcommands. Execute with "temporal operator [command] [subcommand] [options]". +title: temporal operator +sidebar_label: temporal operator +description: Operator commands in Temporal allow actions on Namespaces, Search Attributes, Clusters and Nexus Endpoints using specific subcommands. Execute with "temporal operator [command] [subcommand] [options]". toc_max_heading_level: 4 keywords: - cli reference @@ -34,1010 +34,2586 @@ keywords: - temporal cli - update tags: - - Temporal CLI + - cli-reference + - cluster + - cluster-health + - cluster-list + - cluster-remove + - cluster-upsert + - command-line-interface-cli + - describe + - namespace + - namespace-create + - namespace-delete + - namespace-describe + - namespace-list + - nexus + - nexus-endpoint + - nexus-endpoint-create + - nexus-endpoint-delete + - nexus-endpoint-get + - nexus-endpoint-list + - nexus-endpoint-update + - operator + - search-attribute + - search-attribute-create + - search-attribute-list + - search-attribute-remove + - system + - temporal-cli + - update --- -Operator commands enable actions on [Namespaces](/namespaces), [Search Attributes](/search-attribute), and [Temporal Clusters](/temporal-service). -These actions are performed through subcommands. +## cluster -To run an Operator command, run `temporal operator [command] [subcommand] [command options]`. +Perform operator actions on Temporal Services (also known as Clusters). -## cluster +``` +temporal operator cluster [subcommand] [options] +``` -Cluster commands enable actions on [Temporal Clusters](/temporal-service). +For example to check Service/Cluster health: -Cluster commands follow this syntax: -`temporal operator [command] [subcommand] [command options]`. +``` +temporal operator cluster health +``` ### describe -The `temporal operator cluster describe` command shows information about the [Cluster](/temporal-service). -This information can include information about other connected services, such as a remote [Codec Server](/codec-server). +View information about a Temporal Cluster (Service), including Cluster Name, +persistence store, and visibility store. Add `--detail` for additional info: + +``` +temporal operator cluster describe [--detail] +``` + +Use the following options to change the behavior of this command. -Use the following options to change the output of this command. +**Flags:** -- [--address](/cli/cmd-options#address) +**--detail** _bool_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Show history shard count and Cluster/Service version information. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**Global Flags:** -- [--color](/cli/cmd-options#color) +**--address** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--env](/cli/cmd-options#env) +**--api-key** _string_ -- [--fields](/cli/cmd-options#fields) +API key for request. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--codec-auth** _string_ -- [--namespace](/cli/cmd-options#namespace) +Authorization header for Codec Server requests. -- [--output](/cli/cmd-options#output) +**--codec-endpoint** _string_ -- [--tls](/cli/cmd-options#tls) +Remote Codec Server endpoint. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--codec-header** _string[]_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--color** _string-enum_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--command-timeout** _duration_ -### health +The command execution timeout. 0s means no timeout. -The `temporal operator cluster health` command checks the health of the [Frontend Service](/temporal-service/temporal-server#frontend-service). -A successful execution returns a list of [Cluster](/temporal-service) metrics. +**--env** _string_ -Use the following options to change the behavior and output of this command. +Active environment name (`ENV`). (default "default") -- [--address](/cli/cmd-options#address) +**--env-file** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--grpc-meta** _string[]_ -- [--color](/cli/cmd-options#color) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--log-format** _string-enum_ -- [--env](/cli/cmd-options#env) +Log format. Accepted values: text, json. (default "text") -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--log-level** _string-enum_ -- [--namespace](/cli/cmd-options#namespace) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--tls](/cli/cmd-options#tls) +**--namespace**, **-n** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Temporal Service Namespace. (default "default") -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--no-json-shorthand-payloads** _bool_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Raw payload output, even if the JSON option was used. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--output**, **-o** _string-enum_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -### list +**--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. -The `temporal operator cluster list` command prints a list of all remote [Clusters](/temporal-service) on the system. +**--tls-ca-data** _string_ -`temporal operator cluster list` +Data for server CA certificate. Can't be used with --tls-ca-path. -Use the following options to change the command's behavior. +**--tls-ca-path** _string_ -- [--address](/cli/cmd-options#address) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--tls-cert-data** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--color](/cli/cmd-options#color) +**--tls-cert-path** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--env](/cli/cmd-options#env) +**--tls-disable-host-verification** _bool_ -- [--fields](/cli/cmd-options#fields) +Disable TLS host-name verification. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--tls-key-data** _string_ -- [--limit](/cli/cmd-options#limit) +Private certificate key data. Can't be used with --tls-key-path. -- [--namespace](/cli/cmd-options#namespace) +**--tls-key-path** _string_ -- [--no-pager](/cli/cmd-options#no-pager) +Path to x509 private key. Can't be used with --tls-key-data. -- [--output](/cli/cmd-options#output) +**--tls-server-name** _string_ -- [--pager](/cli/cmd-options#pager) +Override target TLS server name. -- [--time-format](/cli/cmd-options#time-format) +### health + +View information about the health of a Temporal Service: -- [--tls](/cli/cmd-options#tls) +``` +temporal operator cluster health +``` -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Use the following options to change the behavior of this command. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**Global Flags:** -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--address** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--api-key** _string_ -### remove +API key for request. -The `temporal operator cluster remove` command removes a remote [Cluster](/temporal-service) from the system. +**--codec-auth** _string_ -`temporal operator cluster remove --name=SomeCluster` +Authorization header for Codec Server requests. -Use the following options to change the command's behavior. +**--codec-endpoint** _string_ -- [--address](/cli/cmd-options#address) +Remote Codec Server endpoint. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--codec-header** _string[]_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--color](/cli/cmd-options#color) +**--color** _string-enum_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--env](/cli/cmd-options#env) +**--command-timeout** _duration_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +The command execution timeout. 0s means no timeout. -- [--name](/cli/cmd-options#name) +**--env** _string_ -- [--namespace](/cli/cmd-options#namespace) +Active environment name (`ENV`). (default "default") -- [--tls](/cli/cmd-options#tls) +**--env-file** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--grpc-meta** _string[]_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--log-format** _string-enum_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Log format. Accepted values: text, json. (default "text") -### system +**--log-level** _string-enum_ -The `temporal operator cluster system` command provides information about the system the [Cluster](/temporal-service) is running on. -This information can be used to diagnose problems occurring in the [Temporal Server](/temporal-service/temporal-server). +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -`temporal operator cluster system` +**--namespace**, **-n** _string_ -Use the following options to change this command's behavior. +Temporal Service Namespace. (default "default") -- [--address](/cli/cmd-options#address) +**--no-json-shorthand-payloads** _bool_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Raw payload output, even if the JSON option was used. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--output**, **-o** _string-enum_ -- [--color](/cli/cmd-options#color) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--command-timeout](/cli/cmd-options#command-timeout) +**--time-format** _string-enum_ -- [--env](/cli/cmd-options#env) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--fields](/cli/cmd-options#fields) +**--tls** _bool_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--namespace](/cli/cmd-options#namespace) +**--tls-ca-data** _string_ -- [--output](/cli/cmd-options#output) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--tls](/cli/cmd-options#tls) +**--tls-ca-path** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--tls-cert-data** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--tls-cert-path** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Path to x509 certificate. Can't be used with --tls-cert-data. -### upsert +**--tls-disable-host-verification** _bool_ -The `temporal operator cluster upsert` command allows the user to add or update a remote [Cluster](/temporal-service). -`temporal operator cluster upsert --frontend-address="127.0.2.1"` +Disable TLS host-name verification. -Upserting can also be used to enable or disabled cross-cluster connection. -`temporal operator cluster upsert --enable-connection=true` +**--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. + +### list + +Print a list of remote Temporal Clusters (Services) registered to the local +Service. Report details include the Cluster's name, ID, address, History Shard +count, Failover version, and availability: + +``` +temporal operator cluster list [--limit max-count] +``` Use the following options to change the behavior of this command. -- [--address](/cli/cmd-options#address) +**Flags:** -- [--codec-auth](/cli/cmd-options#codec-auth) +**--limit** _int_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Maximum number of Clusters to display. -- [--color](/cli/cmd-options#color) +**Global Flags:** -- [--command-timeout](/cli/cmd-options#command-timeout) +**--address** _string_ -- [--enable-connection](/cli/cmd-options#enable-connection) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--env](/cli/cmd-options#env) +**--api-key** _string_ -- [--frontend-address](/cli/cmd-options#frontend-address) +API key for request. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--codec-auth** _string_ -- [--namespace](/cli/cmd-options#namespace) +Authorization header for Codec Server requests. -- [--tls](/cli/cmd-options#tls) +**--codec-endpoint** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Remote Codec Server endpoint. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--codec-header** _string[]_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--color** _string-enum_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Output coloring. Accepted values: always, never, auto. (default "auto") -## namespace +**--command-timeout** _duration_ -Namespace commands perform operations on [Namespaces](/namespaces) contained in the [Temporal Cluster](/temporal-service). +The command execution timeout. 0s means no timeout. -Namespace commands follow this syntax: -`temporal operator namespace COMMAND [ARGS]`. +**--env** _string_ -### create +Active environment name (`ENV`). (default "default") -The `temporal operator namespace create` command creates a new [Namespace](/namespaces). -The Namespace can be created on the active [Cluster](/temporal-service), or any named Cluster within the system. -`temporal operator namespace --cluster=MyCluster` +**--env-file** _string_ -Global Namespaces can also be created. -`temporal operator namespace create --global` +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -Other settings, such as [retention](/temporal-service/temporal-server#retention-period) and [Visibility Archival State](/temporal-service/visibility), can be configured according to the application's needs. -The Visibility Archive can be set on a separate URI. -`temporal operator namespace create --retention=RetentionMyWorkflow --visibility-archival-state="enabled" --visibility-uri="some-uri"` +**--grpc-meta** _string[]_ -Use the options listed below to change the command's behavior. +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--active-cluster](/cli/cmd-options#active-cluster) +**--log-format** _string-enum_ -- [--address](/cli/cmd-options#address) +Log format. Accepted values: text, json. (default "text") -- [--cluster](/cli/cmd-options#cluster) +**--log-level** _string-enum_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--namespace**, **-n** _string_ -- [--color](/cli/cmd-options#color) +Temporal Service Namespace. (default "default") -- [--command-timeout](/cli/cmd-options#command-timeout) +**--no-json-shorthand-payloads** _bool_ -- [--data](/cli/cmd-options#data) +Raw payload output, even if the JSON option was used. -- [--description](/cli/cmd-options#description) +**--output**, **-o** _string-enum_ -- [--email](/cli/cmd-options#email) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--env](/cli/cmd-options#env) +**--time-format** _string-enum_ -- [--global](/cli/cmd-options#global) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--tls** _bool_ -- [--history-archival-state](/cli/cmd-options#history-archival-state) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--history-uri](/cli/cmd-options#history-uri) +**--tls-ca-data** _string_ -- [--namespace](/cli/cmd-options#namespace) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--retention](/cli/cmd-options#retention) +**--tls-ca-path** _string_ -- [--tls](/cli/cmd-options#tls) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--tls-cert-data** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls-cert-path** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--tls-disable-host-verification** _bool_ -- [--visibility-archival-state](/cli/cmd-options#visibility-archival-state) +Disable TLS host-name verification. -- [--visibility-uri](/cli/cmd-options#visibility-uri) +**--tls-key-data** _string_ -### delete +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. -The `temporal operator namespace delete` command deletes a given [Namespace](/namespaces) from the system. -The command follow the syntax `temporal operator namespace delete ` +**--tls-server-name** _string_ + +Override target TLS server name. + +### remove + +Remove a registered remote Temporal Cluster (Service) from the local Service. + +``` +temporal operator cluster remove \ + --name YourClusterName +``` Use the following options to change the behavior of this command. -- [--address](/cli/cmd-options#address) +**Flags:** -- [--codec-auth](/cli/cmd-options#codec-auth) +**--name** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Cluster/Service name. Required. -- [--color](/cli/cmd-options#color) +**Global Flags:** -- [--command-timeout](/cli/cmd-options#command-timeout) +**--address** _string_ -- [--env](/cli/cmd-options#env) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--api-key** _string_ -- [--namespace](/cli/cmd-options#namespace) +API key for request. -- [--tls](/cli/cmd-options#tls) +**--codec-auth** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Authorization header for Codec Server requests. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--codec-endpoint** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Remote Codec Server endpoint. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--codec-header** _string[]_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--yes](/cli/cmd-options#yes) +**--color** _string-enum_ -### describe +Output coloring. Accepted values: always, never, auto. (default "auto") -The `temporal operator namespace describe` command provides a description of a [Namespace](/namespaces). -Namespaces are identified by Namespace ID. +**--command-timeout** _duration_ -`temporal operator namespace describe --namespace-id=meaningful-business-id` +The command execution timeout. 0s means no timeout. -Use the following options to change the behavior of this command. +**--env** _string_ -- [--address](/cli/cmd-options#address) +Active environment name (`ENV`). (default "default") -- [--codec-auth](/cli/cmd-options#codec-auth) +**--env-file** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--color](/cli/cmd-options#color) +**--grpc-meta** _string[]_ -- [--command-timeout](/cli/cmd-options#command-timeout) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--env](/cli/cmd-options#env) +**--log-format** _string-enum_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Log format. Accepted values: text, json. (default "text") -- [--namespace](/cli/cmd-options#namespace) +**--log-level** _string-enum_ -- [--namespace-id](/cli/cmd-options#namespace-id) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--tls](/cli/cmd-options#tls) +**--namespace**, **-n** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Temporal Service Namespace. (default "default") -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--no-json-shorthand-payloads** _bool_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Raw payload output, even if the JSON option was used. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--output**, **-o** _string-enum_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -### list +**--time-format** _string-enum_ -The `temporal operator namespace list` command lists all [Namespaces](/namespaces) on the [Server](/temporal-service/temporal-server#frontend-service). +Time format. Accepted values: relative, iso, raw. (default "relative") -`temporal operator namespace list` +**--tls** _bool_ -Use the following options to change this command's behavior. +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--address](/cli/cmd-options#address) +**--tls-ca-data** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--tls-ca-path** _string_ -- [--color](/cli/cmd-options#color) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--tls-cert-data** _string_ -- [--env](/cli/cmd-options#env) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--tls-cert-path** _string_ -- [--namespace](/cli/cmd-options#namespace) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--tls](/cli/cmd-options#tls) +**--tls-disable-host-verification** _bool_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Disable TLS host-name verification. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--tls-key-data** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--tls-key-path** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Path to x509 private key. Can't be used with --tls-key-data. -### update +**--tls-server-name** _string_ + +Override target TLS server name. -The `temporal operator namespace update` command updates a [Namespace](/namespaces). +### system -Namespaces can be assigned a different active [Cluster](/temporal-service). -`temporal operator namespace update --active-cluster=NewActiveCluster` +Show Temporal Server information for Temporal Clusters (Service): Server +version, scheduling support, and more. This information helps diagnose +problems with the Temporal Server. -Namespaces can also be promoted to global Namespaces. -`temporal operator namespace --promote-global=true` +The command defaults to the local Service. Otherwise, use the +`--frontend-address` option to specify a Cluster (Service) endpoint: -Any [Archives](/temporal-service/archival) that were previously enabled or disabled can be changed through this command. -However, URI values for archival states cannot be changed after the states are enabled. -`temporal operator namespace update --history-archival-state="enabled" --visibility-archival-state="disabled"` +``` +temporal operator cluster system \ + --frontend-address "YourRemoteEndpoint:YourRemotePort" +``` -:::note +Use the following options to change the behavior of this command. -The Namespace needs to be the last argument passed in your command. -For example, `temporal operator namespace update --retention 180 your_namespace`. +**Global Flags:** -::: +**--address** _string_ -Use the options listed below to change the command's behavior. +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--active-cluster](/cli/cmd-options#active-cluster) +**--api-key** _string_ -- [--address](/cli/cmd-options#address) +API key for request. -- [--cluster](/cli/cmd-options#cluster) +**--codec-auth** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Authorization header for Codec Server requests. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--codec-endpoint** _string_ -- [--color](/cli/cmd-options#color) +Remote Codec Server endpoint. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--codec-header** _string[]_ -- [--data](/cli/cmd-options#data) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--description](/cli/cmd-options#description) +**--color** _string-enum_ -- [--email](/cli/cmd-options#email) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--env](/cli/cmd-options#env) +**--command-timeout** _duration_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +The command execution timeout. 0s means no timeout. -- [--history-archival-state](/cli/cmd-options#history-archival-state) +**--env** _string_ -- [--history-uri](/cli/cmd-options#history-uri) +Active environment name (`ENV`). (default "default") -- [--namespace](/cli/cmd-options#namespace) +**--env-file** _string_ -- [--promote-global](/cli/cmd-options#promote-global) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--retention](/cli/cmd-options#retention) +**--grpc-meta** _string[]_ -- [--tls](/cli/cmd-options#tls) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--log-format** _string-enum_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Log format. Accepted values: text, json. (default "text") -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--log-level** _string-enum_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--namespace**, **-n** _string_ -- [--verbose](/cli/cmd-options#verbose) +Temporal Service Namespace. (default "default") -- [--visibility-archival-state](/cli/cmd-options#visibility-archival-state) +**--no-json-shorthand-payloads** _bool_ -- [--visibility-uri](/cli/cmd-options#visibility-uri) +Raw payload output, even if the JSON option was used. -## nexus +**--output**, **-o** _string-enum_ -These commands manage Nexus resources. +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -Nexus commands follow this syntax: +**--time-format** _string-enum_ -``` -temporal operator nexus [command] [subcommand] [options] -``` +Time format. Accepted values: relative, iso, raw. (default "relative") -### endpoint +**--tls** _bool_ -These commands manage Nexus Endpoints. +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -Nexus Endpoint commands follow this syntax: +**--tls-ca-data** _string_ -``` -temporal operator nexus endpoint [command] [options] -``` +Data for server CA certificate. Can't be used with --tls-ca-path. -#### create +**--tls-ca-path** _string_ -Create a Nexus Endpoint on the Server. +Path to server CA certificate. Can't be used with --tls-ca-data. -A Nexus Endpoint name is used in Workflow code to invoke Nexus Operations. -The endpoint target may either be a Worker, in which case `--target-namespace` and `--target-task-queue` must both be provided, or an external URL, in which case `--target-url` must be provided. +**--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. -This command will fail if an endpoint with the same name is already registered. +**--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. + +### upsert + +Add, remove, or update a registered ("remote") Temporal Cluster (Service). ``` -temporal operator nexus endpoint create \ - --name your-endpoint \ - --target-namespace your-namespace \ - --target-task-queue your-task-queue \ - --description-file DESCRIPTION.md +temporal operator cluster upsert [options] +``` + +For example: + +``` +temporal operator cluster upsert \ + --frontend-address "YourRemoteEndpoint:YourRemotePort" + --enable-connection false ``` Use the following options to change the behavior of this command. -- [--address](/cli/cmd-options#address) +**Flags:** -- [--api-key](/cli/cmd-options#api-key) +**--enable-connection** _bool_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Set the connection to "enabled". -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--frontend-address** _string_ -- [--color](/cli/cmd-options#color) +Remote endpoint. Required. -- [--command-timeout](/cli/cmd-options#command-timeout) +**Global Flags:** -- [--description](/cli/cmd-options#description) +**--address** _string_ -- [--description-file](/cli/cmd-options#description-file) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--env](/cli/cmd-options#env) +**--api-key** _string_ -- [--env-file](/cli/cmd-options#env-file) +API key for request. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--codec-auth** _string_ -- [--log-format](/cli/cmd-options#log-format) +Authorization header for Codec Server requests. -- [--log-level](/cli/cmd-options#log-level) +**--codec-endpoint** _string_ -- [--name](/cli/cmd-options#name) +Remote Codec Server endpoint. -- [--namespace](/cli/cmd-options#namespace) +**--codec-header** _string[]_ -- [--no-json-shorthand-payloads](/cli/cmd-options#no-json-shorthand-payloads) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--output](/cli/cmd-options#output) +**--color** _string-enum_ -- [--target-namespace](/cli/cmd-options#target-namespace) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--target-task-queue](/cli/cmd-options#target-task-queue) +**--command-timeout** _duration_ -- [--target-url](/cli/cmd-options#target-url) +The command execution timeout. 0s means no timeout. -- [--time-format](/cli/cmd-options#time-format) +**--env** _string_ -- [--tls](/cli/cmd-options#tls) +Active environment name (`ENV`). (default "default") -- [--tls-ca-data](/cli/cmd-options#tls-ca-data) +**--env-file** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--tls-cert-data](/cli/cmd-options#tls-cert-data) +**--grpc-meta** _string[]_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--log-format** _string-enum_ -- [--tls-key-data](/cli/cmd-options#tls-key-data) +Log format. Accepted values: text, json. (default "text") -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--log-level** _string-enum_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -#### delete +**--namespace**, **-n** _string_ -Delete a Nexus Endpoint from the Server. +Temporal Service Namespace. (default "default") -``` -temporal operator nexus endpoint delete --name your-endpoint -``` +**--no-json-shorthand-payloads** _bool_ -Use the following options to change the behavior of this command. +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") + +**--time-format** _string-enum_ -- [--address](/cli/cmd-options#address) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--api-key](/cli/cmd-options#api-key) +**--tls** _bool_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--tls-ca-data** _string_ -- [--color](/cli/cmd-options#color) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--tls-ca-path** _string_ -- [--env](/cli/cmd-options#env) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--env-file](/cli/cmd-options#env-file) +**--tls-cert-data** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--log-format](/cli/cmd-options#log-format) +**--tls-cert-path** _string_ -- [--log-level](/cli/cmd-options#log-level) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--name](/cli/cmd-options#name) +**--tls-disable-host-verification** _bool_ -- [--namespace](/cli/cmd-options#namespace) +Disable TLS host-name verification. -- [--no-json-shorthand-payloads](/cli/cmd-options#no-json-shorthand-payloads) +**--tls-key-data** _string_ -- [--output](/cli/cmd-options#output) +Private certificate key data. Can't be used with --tls-key-path. -- [--time-format](/cli/cmd-options#time-format) +**--tls-key-path** _string_ -- [--tls](/cli/cmd-options#tls) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls-ca-data](/cli/cmd-options#tls-ca-data) +**--tls-server-name** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Override target TLS server name. -- [--tls-cert-data](/cli/cmd-options#tls-cert-data) +## namespace -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Manage Temporal Cluster (Service) Namespaces: -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +``` +temporal operator namespace [command] [command options] +``` -- [--tls-key-data](/cli/cmd-options#tls-key-data) +For example: -- [--tls-key-path](/cli/cmd-options#tls-key-path) +``` +temporal operator namespace create \ + --namespace YourNewNamespaceName +``` -- [--tls-server-name](/cli/cmd-options#tls-server-name) +### create -#### get +Create a new Namespace on the Temporal Service: -Get a Nexus Endpoint by name from the Server. +``` +temporal operator namespace create \ + --namespace YourNewNamespaceName \ + [options] +```` + +Create a Namespace with multi-region data replication: ``` -temporal operator nexus endpoint get --name your-endpoint +temporal operator namespace create \ + --global \ + --namespace YourNewNamespaceName +``` + +Configure settings like retention and Visibility Archival State as needed. +For example, the Visibility Archive can be set on a separate URI: + ``` +temporal operator namespace create \ + --retention 5d \ + --visibility-archival-state enabled \ + --visibility-uri YourURI \ + --namespace YourNewNamespaceName +``` + +Note: URI values for archival states can't be changed once enabled. Use the following options to change the behavior of this command. -- [--address](/cli/cmd-options#address) +**Flags:** -- [--api-key](/cli/cmd-options#api-key) +**--active-cluster** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Active Cluster (Service) name. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--cluster** _string[]_ -- [--color](/cli/cmd-options#color) +Cluster (Service) names for Namespace creation. Can be passed multiple times. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--data** _string[]_ -- [--env](/cli/cmd-options#env) +Namespace data as `KEY=VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. -- [--env-file](/cli/cmd-options#env-file) +**--description** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Namespace description. -- [--log-format](/cli/cmd-options#log-format) +**--email** _string_ -- [--log-level](/cli/cmd-options#log-level) +Owner email. -- [--name](/cli/cmd-options#name) +**--global** _bool_ -- [--namespace](/cli/cmd-options#namespace) +Enable multi-region data replication. -- [--no-json-shorthand-payloads](/cli/cmd-options#no-json-shorthand-payloads) +**--history-archival-state** _string-enum_ -- [--output](/cli/cmd-options#output) +History archival state. Accepted values: disabled, enabled. (default "disabled") -- [--time-format](/cli/cmd-options#time-format) +**--history-uri** _string_ -- [--tls](/cli/cmd-options#tls) +Archive history to this `URI`. Once enabled, can't be changed. -- [--tls-ca-data](/cli/cmd-options#tls-ca-data) +**--retention** _duration_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Time to preserve closed Workflows before deletion. (default "72h") -- [--tls-cert-data](/cli/cmd-options#tls-cert-data) +**--visibility-archival-state** _string-enum_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Visibility archival state. Accepted values: disabled, enabled. (default "disabled") -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--visibility-uri** _string_ -- [--tls-key-data](/cli/cmd-options#tls-key-data) +Archive visibility data to this `URI`. Once enabled, can't be changed. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**Global Flags:** -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--address** _string_ -#### list +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -List all Nexus Endpoints on the Server. +**--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. + +**--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. + +**--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") + +**--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. + +**--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. + +### delete + +Removes a Namespace from the Service. ``` -temporal operator nexus endpoint list +temporal operator namespace delete [options] +``` + +For example: + +``` +temporal operator namespace delete \ + --namespace YourNamespaceName ``` Use the following options to change the behavior of this command. -- [--address](/cli/cmd-options#address) +**Flags:** -- [--api-key](/cli/cmd-options#api-key) +**--yes**, **-y** _bool_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Request confirmation before deletion. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**Global Flags:** -- [--color](/cli/cmd-options#color) +**--address** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--env](/cli/cmd-options#env) +**--api-key** _string_ -- [--env-file](/cli/cmd-options#env-file) +API key for request. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--codec-auth** _string_ -- [--log-format](/cli/cmd-options#log-format) +Authorization header for Codec Server requests. -- [--log-level](/cli/cmd-options#log-level) +**--codec-endpoint** _string_ -- [--namespace](/cli/cmd-options#namespace) +Remote Codec Server endpoint. -- [--no-json-shorthand-payloads](/cli/cmd-options#no-json-shorthand-payloads) +**--codec-header** _string[]_ -- [--output](/cli/cmd-options#output) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--time-format](/cli/cmd-options#time-format) +**--color** _string-enum_ -- [--tls](/cli/cmd-options#tls) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--tls-ca-data](/cli/cmd-options#tls-ca-data) +**--command-timeout** _duration_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +The command execution timeout. 0s means no timeout. -- [--tls-cert-data](/cli/cmd-options#tls-cert-data) +**--env** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Active environment name (`ENV`). (default "default") -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--env-file** _string_ -- [--tls-key-data](/cli/cmd-options#tls-key-data) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--grpc-meta** _string[]_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -#### update +**--log-format** _string-enum_ -Update an existing Nexus Endpoint on the Server. +Log format. Accepted values: text, json. (default "text") -A Nexus Endpoint name is used in Workflow code to invoke Nexus Operations. -The endpoint target may either be a Worker, in which case `--target-namespace` and `--target-task-queue` must both be provided, or an external URL, in which case `--target-url` must be provided. +**--log-level** _string-enum_ -The endpoint is patched; existing fields for which flags are not provided are -left as they were. +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -Update only the target task queue: +**--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") + +**--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. + +**--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. + +### describe + +Provide long-form information about a Namespace identified by its ID or name: ``` -temporal operator nexus endpoint update \ - --name your-endpoint \ - --target-task-queue your-other-queue +temporal operator namespace describe \ + --namespace-id YourNamespaceId ``` -Update only the description: +or ``` -temporal operator nexus endpoint update \ - --name your-endpoint \ - --description-file DESCRIPTION.md +temporal operator namespace describe \ + --namespace YourNamespaceName ``` Use the following options to change the behavior of this command. -- [--address](/cli/cmd-options#address) +**Flags:** -- [--api-key](/cli/cmd-options#api-key) +**--namespace-id** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Namespace ID. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**Global Flags:** -- [--color](/cli/cmd-options#color) +**--address** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--description](/cli/cmd-options#description) +**--api-key** _string_ -- [--description-file](/cli/cmd-options#description-file) +API key for request. -- [--env](/cli/cmd-options#env) +**--codec-auth** _string_ -- [--env-file](/cli/cmd-options#env-file) +Authorization header for Codec Server requests. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--codec-endpoint** _string_ -- [--log-format](/cli/cmd-options#log-format) +Remote Codec Server endpoint. -- [--log-level](/cli/cmd-options#log-level) +**--codec-header** _string[]_ -- [--name](/cli/cmd-options#name) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--namespace](/cli/cmd-options#namespace) +**--color** _string-enum_ -- [--no-json-shorthand-payloads](/cli/cmd-options#no-json-shorthand-payloads) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--output](/cli/cmd-options#output) +**--command-timeout** _duration_ -- [--target-namespace](/cli/cmd-options#target-namespace) +The command execution timeout. 0s means no timeout. -- [--target-task-queue](/cli/cmd-options#target-task-queue) +**--env** _string_ -- [--target-url](/cli/cmd-options#target-url) +Active environment name (`ENV`). (default "default") -- [--time-format](/cli/cmd-options#time-format) +**--env-file** _string_ -- [--tls](/cli/cmd-options#tls) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--tls-ca-data](/cli/cmd-options#tls-ca-data) +**--grpc-meta** _string[]_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-cert-data](/cli/cmd-options#tls-cert-data) +**--log-format** _string-enum_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Log format. Accepted values: text, json. (default "text") -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--log-level** _string-enum_ -- [--tls-key-data](/cli/cmd-options#tls-key-data) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--namespace**, **-n** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Temporal Service Namespace. (default "default") -- [--unset-description](/cli/cmd-options#unset-description) +**--no-json-shorthand-payloads** _bool_ -## search-attribute +Raw payload output, even if the JSON option was used. -Search Attribute commands enable operations for the creation, listing, and removal of [Search Attributes](/search-attribute). +**--output**, **-o** _string-enum_ -Search Attribute commands follow this syntax: -`temporal operator search-attribute COMMAND [ARGS]`. +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -### create +**--time-format** _string-enum_ -The `temporal operator search-attribute create` command adds one or more custom [Search Attributes](/search-attribute). -These Search Attributes can be used to [filter a list](/list-filter) of [Workflow Executions](/workflow-execution) that contain the given Search Attributes in their metadata. +Time format. Accepted values: relative, iso, raw. (default "relative") -Use the following options to change this command's behavior. +**--tls** _bool_ -- [--fields](/cli/cmd-options#fields) -- [--address](/cli/cmd-options#address) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--tls-ca-data** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--color](/cli/cmd-options#color) +**--tls-ca-path** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--env](/cli/cmd-options#env) +**--tls-cert-data** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--name](/cli/cmd-options#name) +**--tls-cert-path** _string_ -- [--namespace](/cli/cmd-options#namespace) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--tls](/cli/cmd-options#tls) +**--tls-disable-host-verification** _bool_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Disable TLS host-name verification. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--tls-key-data** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--tls-key-path** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Path to x509 private key. Can't be used with --tls-key-data. -- [--type](/cli/cmd-options#type) +**--tls-server-name** _string_ + +Override target TLS server name. ### list -The `temporal operator search-attribute list` command displays a list of all [Search Attributes](/search-attribute) that can be used in [Queries](/sending-messages#sending-queries). +Display a detailed listing for all Namespaces on the Service: + +``` +temporal operator namespace list +``` -`temporal workflow list --query`. +Use the following options to change the behavior of this command. -Use the following options to change this command's behavior. +**Global Flags:** -- [--address](/cli/cmd-options#address) +**--address** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--api-key** _string_ -- [--color](/cli/cmd-options#color) +API key for request. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--codec-auth** _string_ -- [--env](/cli/cmd-options#env) +Authorization header for Codec Server requests. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--codec-endpoint** _string_ -- [--namespace](/cli/cmd-options#namespace) +Remote Codec Server endpoint. -- [--output](/cli/cmd-options#output) +**--codec-header** _string[]_ -- [--tls](/cli/cmd-options#tls) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--color** _string-enum_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--command-timeout** _duration_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +The command execution timeout. 0s means no timeout. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--env** _string_ -### remove +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. + +**--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") + +**--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. + +**--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 + +Update a Namespace using properties you specify. + +``` +temporal operator namespace update [options] +``` + +Assign a Namespace's active Cluster (Service): + +``` +temporal operator namespace update \ + --namespace YourNamespaceName \ + --active-cluster NewActiveCluster +``` + +Promote a Namespace for multi-region data replication: + +``` +temporal operator namespace update \ + --namespace YourNamespaceName \ + --promote-global +``` + +You may update archives that were previously enabled or disabled. Note: URI +values for archival states can't be changed once enabled. + +``` +temporal operator namespace update \ + --namespace YourNamespaceName \ + --history-archival-state enabled \ + --visibility-archival-state disabled +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--active-cluster** _string_ + +Active Cluster (Service) name. + +**--cluster** _string[]_ + +Cluster (Service) names. + +**--data** _string[]_ + +Namespace data as `KEY=VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--description** _string_ + +Namespace description. + +**--email** _string_ + +Owner email. + +**--history-archival-state** _string-enum_ + +History archival state. Accepted values: disabled, enabled. + +**--history-uri** _string_ + +Archive history to this `URI`. Once enabled, can't be changed. + +**--promote-global** _bool_ + +Enable multi-region data replication. + +**--retention** _duration_ + +Length of time a closed Workflow is preserved before deletion. + +**--visibility-archival-state** _string-enum_ + +Visibility archival state. Accepted values: disabled, enabled. + +**--visibility-uri** _string_ + +Archive visibility data to this `URI`. Once enabled, can't be changed. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +## nexus + +These commands manage Nexus resources. + +Nexus commands follow this syntax: + +``` +temporal operator nexus [command] [subcommand] [options] +``` + +### endpoint + +These commands manage Nexus Endpoints. + +Nexus Endpoint commands follow this syntax: + +``` +temporal operator nexus endpoint [command] [options] +``` + +#### create + +Create a Nexus Endpoint on the Server. + +A Nexus Endpoint name is used in Workflow code to invoke Nexus Operations. +The endpoint target may either be a Worker, in which case +`--target-namespace` and `--target-task-queue` must both be provided, or +an external URL, in which case `--target-url` must be provided. + +This command will fail if an Endpoint with the same name is already +registered. + +``` +temporal operator nexus endpoint create \ + --name your-endpoint \ + --target-namespace your-namespace \ + --target-task-queue your-task-queue \ + --description-file DESCRIPTION.md +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--description** _string_ + +Nexus Endpoint description. You may use Markdown formatting in the Nexus Endpoint description. + +**--description-file** _string_ + +Path to the Nexus Endpoint description file. The contents of the description file may use Markdown formatting. + +**--name** _string_ + +Endpoint name. Required. + +**--target-namespace** _string_ + +Namespace where a handler Worker polls for Nexus tasks. + +**--target-task-queue** _string_ + +Task Queue that a handler Worker polls for Nexus tasks. + +**--target-url** _string_ + +An external Nexus Endpoint that receives forwarded Nexus requests. May be used as an alternative to `--target-namespace` and `--target-task-queue`. + +:::note + +Option is experimental. + +::: + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +#### delete + +Delete a Nexus Endpoint from the Server. + +``` +temporal operator nexus endpoint delete --name your-endpoint +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--name** _string_ + +Endpoint name. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +#### get + +Get a Nexus Endpoint by name from the Server. + +``` +temporal operator nexus endpoint get --name your-endpoint +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--name** _string_ + +Endpoint name. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +#### list + +List all Nexus Endpoints on the Server. + +``` +temporal operator nexus endpoint list +``` + +Use the following options to change the behavior of this command. + +**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. + +**--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. + +**--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") + +**--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. + +**--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 + +Update an existing Nexus Endpoint on the Server. + +A Nexus Endpoint name is used in Workflow code to invoke Nexus Operations. +The Endpoint target may either be a Worker, in which case +`--target-namespace` and `--target-task-queue` must both be provided, or +an external URL, in which case `--target-url` must be provided. + +The Endpoint is patched; existing fields for which flags are not provided +are left as they were. + +Update only the target task queue: + +``` +temporal operator nexus endpoint update \ + --name your-endpoint \ + --target-task-queue your-other-queue +``` + +Update only the description: + +``` +temporal operator nexus endpoint update \ + --name your-endpoint \ + --description-file DESCRIPTION.md +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--description** _string_ + +Nexus Endpoint description. You may use Markdown formatting in the Nexus Endpoint description. + +**--description-file** _string_ + +Path to the Nexus Endpoint description file. The contents of the description file may use Markdown formatting. + +**--name** _string_ + +Endpoint name. Required. + +**--target-namespace** _string_ + +Namespace where a handler Worker polls for Nexus tasks. + +**--target-task-queue** _string_ + +Task Queue that a handler Worker polls for Nexus tasks. + +**--target-url** _string_ + +An external Nexus Endpoint that receives forwarded Nexus requests. May be used as an alternative to `--target-namespace` and `--target-task-queue`. + +:::note + +Option is experimental. + +::: + +**--unset-description** _bool_ + +Unset the description. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +## search-attribute + +Create, list, or remove Search Attributes fields stored in a Workflow +Execution's metadata: + +``` +temporal operator search-attribute create \ + --name YourAttributeName \ + --type Keyword +``` + +Supported types include: Text, Keyword, Int, Double, Bool, Datetime, and +KeywordList. + +If you wish to delete a Search Attribute, please contact support +at https://support.temporal.io. + +### create + +Add one or more custom Search Attributes: + +``` +temporal operator search-attribute create \ + --name YourAttributeName \ + --type Keyword +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--name** _string[]_ + +Search Attribute name. Required. + +**--type** _string-enum[]_ + +Search Attribute type. Required. Accepted values: Text, Keyword, Int, Double, Bool, Datetime, KeywordList. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +### list + +Display a list of active Search Attributes that can be assigned or used with +Workflow Queries. You can manage this list and add attributes as needed: + +``` +temporal operator search-attribute list +``` + +Use the following options to change the behavior of this command. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +### remove + +Remove custom Search Attributes from the options that can be assigned or used +with Workflow Queries. + +``` +temporal operator search-attribute remove \ + --name YourAttributeName +``` + +Remove attributes without confirmation: + +``` +temporal operator search-attribute remove \ + --name YourAttributeName \ + --yes +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--name** _string[]_ + +Search Attribute name. Required. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm removal. + +**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. + +**--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. + +**--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") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ -The `temporal operator search-attribute remove` command removes custom [Search Attribute](/search-attribute) metadata. -This command does not remove custom Search Attributes from Elasticsearch or change the index schema. +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -Use the following options to change this command's behavior. +**--tls-ca-data** _string_ -- [--address](/cli/cmd-options#address) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--tls-ca-path** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--color](/cli/cmd-options#color) +**--tls-cert-data** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--env](/cli/cmd-options#env) +**--tls-cert-path** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--name](/cli/cmd-options#name) +**--tls-disable-host-verification** _bool_ -- [--namespace](/cli/cmd-options#namespace) +Disable TLS host-name verification. -- [--tls](/cli/cmd-options#tls) +**--tls-key-data** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--tls-key-path** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--tls-server-name** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Override target TLS server name. -- [--yes](/cli/cmd-options#yes) diff --git a/docs/cli/schedule.mdx b/docs/cli/schedule.mdx index ed9b453be6..83c6f340b5 100644 --- a/docs/cli/schedule.mdx +++ b/docs/cli/schedule.mdx @@ -1,7 +1,7 @@ --- id: schedule -title: Temporal CLI schedule command reference -sidebar_label: schedule +title: temporal schedule +sidebar_label: temporal schedule description: Temporal's Schedule commands allow users to create, update, and manage Workflow Executions seamlessly for automation, supporting commands for creation, backfill, deletion, and more. toc_max_heading_level: 4 keywords: @@ -20,525 +20,1324 @@ keywords: - temporal cli - updates tags: - - Temporal CLI - - Schedules + - backfill + - cli-reference + - command-line-interface-cli + - schedule + - schedule-backfill + - schedule-create + - schedule-delete + - schedule-describe + - schedule-list + - schedule-toggle + - schedule-trigger + - schedule-update + - temporal-cli + - updates --- -Schedule commands allow the user to create, use, and update [Schedules](/schedule). -Schedules control when certain Actions for a [Workflow Execution](/workflow-execution) are performed, making it a useful tool for automation. - -To run a Schedule command, run `temporal schedule [command] [command options]`. - ## backfill -The `temporal schedule backfill` command executes Actions ahead of their specified time range. -Backfilling adds [Workflow Runs]/workflow-execution/workflowid-runid#run-id from a time period when the Schedule was paused, or from before the Schedule was created. +Batch-execute actions that would have run during a specified time interval. +Use this command to fill in Workflow runs from when a Schedule was paused, +before a Schedule was created, from the future, or to re-process a previously +executed interval. + +Backfills require a Schedule ID and the time period covered by the request. +It's best to use the `BufferAll` or `AllowAll` policies to avoid conflicts +and ensure no Workflow Executions are skipped. -Schedule backfills require a valid Schedule ID, along with the time in which to run the Schedule and a change to the overlap policy. -The following example fills in Workflow Runs from a point when the Schedule was paused. +For example: ``` -temporal schedule backfill --schedule-id 'your-schedule-id' \ ---overlap-policy 'BufferAll' \ ---start-time '2022-05-0101T00:00:00Z' \ ---end-time '2022-05-31T23:59:59Z' +temporal schedule backfill \ + --schedule-id "YourScheduleId" \ + --start-time "2022-05-01T00:00:00Z" \ + --end-time "2022-05-31T23:59:59Z" \ + --overlap-policy BufferAll ``` -Temporal recommends setting the Overlap Policy to `BufferAll` to run backfilled Workflows sequentially. +The policies include: + +* **AllowAll**: Allow unlimited concurrent Workflow Executions. This + significantly speeds up the backfilling process on systems that support + concurrency. You must ensure running Workflow Executions do not interfere + with each other. +* **BufferAll**: Buffer all incoming Workflow Executions while waiting for + the running Workflow Execution to complete. +* **Skip**: If a previous Workflow Execution is still running, discard new + Workflow Executions. +* **BufferOne**: Same as 'Skip' but buffer a single Workflow Execution to be + run after the previous Execution completes. Discard other Workflow + Executions. +* **CancelOther**: Cancel the running Workflow Execution and replace it with + the incoming new Workflow Execution. +* **TerminateOther**: Terminate the running Workflow Execution and replace + it with the incoming new Workflow Execution. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--end-time** _timestamp_ + +Backfill end time. Required. + +**--start-time** _timestamp_ + +Backfill start time. 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_ -Use the following options to change this command's behavior. +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--address](/cli/cmd-options#address) +**--command-timeout** _duration_ -- [--codec-auth](/cli/cmd-options#codec-auth) +The command execution timeout. 0s means no timeout. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--env** _string_ -- [--color](/cli/cmd-options#color) +Active environment name (`ENV`). (default "default") -- [--command-timeout](/cli/cmd-options#command-timeout) +**--env-file** _string_ -- [--end-time](/cli/cmd-options#end-time) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--env](/cli/cmd-options#env) +**--grpc-meta** _string[]_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--namespace](/cli/cmd-options#namespace) +**--log-format** _string-enum_ -- [--overlap-policy](/cli/cmd-options#overlap-policy) +Log format. Accepted values: text, json. (default "text") -- [--schedule-id](/cli/cmd-options#schedule-id) +**--log-level** _string-enum_ -- [--start-time](/cli/cmd-options#start-time) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--tls](/cli/cmd-options#tls) +**--namespace**, **-n** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Temporal Service Namespace. (default "default") -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--no-json-shorthand-payloads** _bool_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Raw payload output, even if the JSON option was used. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--output**, **-o** _string-enum_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--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. + +**--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. ## create -The `temporal schedule create` command creates a new [Schedule](/schedule). -Newly created Schedules return a Schedule ID to be used in other Schedule commands. +Create a new Schedule on the Temporal Service. A Schedule automatically starts +new Workflow Executions at the times you specify. -Schedules use the following format: +For example: ``` -temporal schedule create \ - --schedule-id 'your-schedule-id' \ - --workflow-id 'your-workflow-id' \ - --task-queue 'your-task-queue' \ - --workflow-type 'YourWorkflowType' + temporal schedule create \ + --schedule-id "YourScheduleId" \ + --calendar '{"dayOfWeek":"Fri","hour":"3","minute":"30"}' \ + --workflow-id YourBaseWorkflowIdName \ + --task-queue YourTaskQueue \ + --type YourWorkflowType ``` -Actions are executed at the times specified in the Schedule. -For example, the following Schedule starts a Workflow every 5 hours at 15 minutes past the hour. -A Workflow is also started at 11:03 on Fridays. +Schedules support any combination of `--calendar`, `--interval`, and `--cron`: + +* Shorthand `--interval` strings. + For example: 45m (every 45 minutes) or 6h/5h (every 6 hours, at the top of + the 5th hour). +* JSON `--calendar`, as in the preceding example. +* Unix-style `--cron` strings and robfig declarations + (@daily/@weekly/@every X/etc). + For example, every Friday at 12:30 PM: `30 12 * * Fri`. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--calendar** _string[]_ + +Calendar specification in JSON. For example: `{"dayOfWeek":"Fri","hour":"17","minute":"5"}`. + +**--catchup-window** _duration_ + +Maximum catch-up time for when the Service is unavailable. + +**--cron** _string[]_ + +Calendar specification in cron string format. For example: `"30 12 * * Fri"`. + +**--end-time** _timestamp_ + +Schedule end time. + +**--execution-timeout** _duration_ + +Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks. + +**--input**, **-i** _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** _bool_ + +Assume inputs are base64-encoded and attempt to decode them. + +**--input-file** _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** _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. + +**--interval** _string[]_ + +Interval duration. For example, 90m, or 60m/15m to include phase offset. + +**--jitter** _duration_ + +Max difference in time from the specification. Vary the start time randomly within this amount. + +**--memo** _string[]_ + +Memo using 'KEY="VALUE"' pairs. Use JSON values. + +**--notes** _string_ + +Initial notes field value. + +**--overlap-policy** _string-enum_ + +Policy for handling overlapping Workflow Executions. Accepted values: Skip, BufferOne, BufferAll, CancelOther, TerminateOther, AllowAll. (default "Skip") + +**--pause-on-failure** _bool_ + +Pause schedule after Workflow failures. + +**--paused** _bool_ + +Pause the Schedule immediately on creation. + +**--remaining-actions** _int_ + +Total allowed actions. Default is zero (unlimited). + +**--run-timeout** _duration_ + +Fail a Workflow Run if it lasts longer than `DURATION`. + +**--schedule-id**, **-s** _string_ + +Schedule ID. Required. + +**--schedule-memo** _string[]_ + +Set schedule memo using `KEY="VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--schedule-search-attribute** _string[]_ + +Set schedule Search Attributes using `KEY="VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--search-attribute** _string[]_ + +Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--start-time** _timestamp_ + +Schedule start time. + +**--static-details** _string_ + +Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines. + +:::note + +Option is experimental. + +::: + +**--static-summary** _string_ + +Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line. + +:::note + +Option is experimental. + +::: + +**--task-queue**, **-t** _string_ + +Workflow Task queue. Required. + +**--task-timeout** _duration_ + +Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s") + +**--time-zone** _string_ + +Interpret calendar specs with the `TZ` time zone. For a list of time zones, see: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. + +**--type** _string_ + +Workflow Type name. Required. + +**--workflow-id**, **-w** _string_ + +Workflow ID. If not supplied, the Service generates a unique ID. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +## delete + +Deletes a Schedule on the front end Service: ``` -temporal schedule create \ - --schedule-id 'your-schedule-id' \ - --interval '5h/15m' \ - --calendar '{"dayOfWeek":"Fri","hour":"11","minute":"3"}' \ - --overlap-policy 'BufferAll' \ - --workflow-id 'your-workflow-id' \ - --task-queue 'your-task-queue' \ - --workflow-type 'YourWorkflowType' +temporal schedule delete \ + --schedule-id YourScheduleId ``` -Workflows don't run in parallel. -Setting the `--overlap-policy` to `BufferAll` allows Workflows to run sequentially if they would overlap. +Removing a Schedule won't affect the Workflow Executions it started that are +still running. To cancel or terminate these Workflow Executions, use `temporal +workflow delete` with the `TemporalScheduledById` Search Attribute instead. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--schedule-id**, **-s** _string_ + +Schedule ID. 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. + +**--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. + +**--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") + +**--time-format** _string-enum_ -Any combination of `--calendar`, `--interval`, and `--cron` is supported. -Traditional cron strings, along with `CronSchedule` features, are also supported. +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. + +**--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. + +## describe + +Show a Schedule configuration, including information about past, current, and +future Workflow runs: ``` -temporal schedule create \ - --schedule-id 'your-schedule-id' \ - --cron '3 11 * * Fri' \ - --workflow-id 'your-workflow-id' \ - --task-queue 'your-task-queue' \ - --workflow-type 'YourWorkflowType' +temporal schedule describe \ + --schedule-id YourScheduleId ``` -Use the following options to change this command's behavior. +Use the following options to change the behavior of this command. -- [--address](/cli/cmd-options#address) +**Flags:** -- [--calendar](/cli/cmd-options#calendar) +**--schedule-id**, **-s** _string_ -- [--catchup-window](/cli/cmd-options#catchup-window) +Schedule ID. Required. -- [--codec-auth](/cli/cmd-options#codec-auth) +**Global Flags:** -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--address** _string_ -- [--color](/cli/cmd-options#color) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--command-timeout](/cli/cmd-options#command-timeout) +**--api-key** _string_ -- [--cron](/cli/cmd-options#cron) +API key for request. -- [--end-time](/cli/cmd-options#end-time) +**--codec-auth** _string_ -- [--env](/cli/cmd-options#env) +Authorization header for Codec Server requests. -- [--execution-timeout](/cli/cmd-options#execution-timeout) +**--codec-endpoint** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Remote Codec Server endpoint. -- [--input](/cli/cmd-options#input) +**--codec-header** _string[]_ -- [--input-file](/cli/cmd-options#input-file) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--interval](/cli/cmd-options#interval) +**--color** _string-enum_ -- [--jitter](/cli/cmd-options#jitter) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--max-field-length](/cli/cmd-options#max-field-length) +**--command-timeout** _duration_ -- [--memo](/cli/cmd-options#memo) +The command execution timeout. 0s means no timeout. -- [--memo-file](/cli/cmd-options#memo-file) +**--env** _string_ -- [--namespace](/cli/cmd-options#namespace) +Active environment name (`ENV`). (default "default") -- [--notes](/cli/cmd-options#notes) +**--env-file** _string_ -- [--overlap-policy](/cli/cmd-options#overlap-policy) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--pause](/cli/cmd-options#pause) +**--grpc-meta** _string[]_ -- [--pause-on-failure](/cli/cmd-options#pause-on-failure) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--remaining-actions](/cli/cmd-options#remaining-actions) +**--log-format** _string-enum_ -- [--run-timeout](/cli/cmd-options#run-timeout) +Log format. Accepted values: text, json. (default "text") -- [--schedule-id](/cli/cmd-options#schedule-id) +**--log-level** _string-enum_ -- [--search-attribute](/cli/cmd-options#search-attribute) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--start-time](/cli/cmd-options#start-time) +**--namespace**, **-n** _string_ -- [--task-queue](/cli/cmd-options#task-queue) +Temporal Service Namespace. (default "default") -- [--task-timeout](/cli/cmd-options#task-timeout) +**--no-json-shorthand-payloads** _bool_ -- [--time-zone](/cli/cmd-options#time-zone) +Raw payload output, even if the JSON option was used. -- [--tls](/cli/cmd-options#tls) +**--output**, **-o** _string-enum_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--time-format** _string-enum_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--tls** _bool_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--workflow-id](/cli/cmd-options#workflow-id) +**--tls-ca-data** _string_ -- [--workflow-type](/cli/cmd-options#workflow-type) +Data for server CA certificate. Can't be used with --tls-ca-path. -## delete +**--tls-ca-path** _string_ -The `temporal schedule delete` command deletes a [Schedule](/schedule). -Deleting a Schedule does not affect any [Workflows](/workflows) started by the Schedule. +Path to server CA certificate. Can't be used with --tls-ca-data. -[Workflow Executions](/workflow-execution) started by Schedules can be cancelled or terminated like other Workflow Executions. -However, Workflow Executions started by a Schedule can be identified by their [Search Attributes](/search-attribute), making them targetable by batch command for termination. +**--tls-cert-data** _string_ -`temporal schedule delete --schedule-id 'your-schedule-id' [command options]` +Data for x509 certificate. Can't be used with --tls-cert-path. -Use the following options to change this command's behavior. +**--tls-cert-path** _string_ -- [--address](/cli/cmd-options#address) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--tls-disable-host-verification** _bool_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Disable TLS host-name verification. -- [--color](/cli/cmd-options#color) +**--tls-key-data** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Private certificate key data. Can't be used with --tls-key-path. -- [--env](/cli/cmd-options#env) +**--tls-key-path** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Path to x509 private key. Can't be used with --tls-key-data. -- [--namespace](/cli/cmd-options#namespace) +**--tls-server-name** _string_ -- [--schedule-id](/cli/cmd-options#schedule-id) +Override target TLS server name. -- [--tls](/cli/cmd-options#tls) +## list -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Lists the Schedules hosted by a Namespace: -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +``` +temporal schedule list \ + --namespace YourNamespace +``` -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Use the following options to change the behavior of this command. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**Flags:** -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--long**, **-l** _bool_ -## describe +Show detailed information. -The `temporal schedule describe` command shows the current [Schedule](/schedule) configuration. -This command also provides information about past, current, and future [Workflow Runs]/workflow-execution/workflowid-runid#run-id. +**--query**, **-q** _string_ -`temporal schedule describe --schedule-id 'your-schedule-id' [command options]` +Filter results using given List Filter. -Use the following options to change this command's behavior. +**--really-long** _bool_ -- [--address](/cli/cmd-options#address) +Show extensive information in non-table form. -- [--codec-auth](/cli/cmd-options#codec-auth) +**Global Flags:** -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--address** _string_ -- [--color](/cli/cmd-options#color) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--command-timeout](/cli/cmd-options#command-timeout) +**--api-key** _string_ -- [--env](/cli/cmd-options#env) +API key for request. -- [--fields](/cli/cmd-options#fields) +**--codec-auth** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Authorization header for Codec Server requests. -- [--namespace](/cli/cmd-options#namespace) +**--codec-endpoint** _string_ -- [--output](/cli/cmd-options#output) +Remote Codec Server endpoint. -- [--raw](/cli/cmd-options#raw) +**--codec-header** _string[]_ -- [--schedule-id](/cli/cmd-options#schedule-id) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--time-format](/cli/cmd-options#time-format) +**--color** _string-enum_ -- [--tls](/cli/cmd-options#tls) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--command-timeout** _duration_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +The command execution timeout. 0s means no timeout. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--env** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Active environment name (`ENV`). (default "default") -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--env-file** _string_ -## list +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. + +**--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") -The `temporal schedule list` command lists all [Schedule](/schedule) configurations. -Listing Schedules in [Standard Visibility](/visibility#standard-visibility) will only provide Schedule IDs. +**--namespace**, **-n** _string_ -`temporal schedule list` +Temporal Service Namespace. (default "default") -Use the options below to change the behavior of this command. +**--no-json-shorthand-payloads** _bool_ -- [--address](/cli/cmd-options#address) +Raw payload output, even if the JSON option was used. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--output**, **-o** _string-enum_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--color](/cli/cmd-options#color) +**--time-format** _string-enum_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--env](/cli/cmd-options#env) +**--tls** _bool_ -- [--fields](/cli/cmd-options#fields) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--tls-ca-data** _string_ -- [--limit](/cli/cmd-options#limit) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--namespace](/cli/cmd-options#namespace) +**--tls-ca-path** _string_ -- [--no-pager](/cli/cmd-options#no-pager) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--output](/cli/cmd-options#output) +**--tls-cert-data** _string_ -- [--pager](/cli/cmd-options#pager) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--time-format](/cli/cmd-options#time-format) +**--tls-cert-path** _string_ -- [--tls](/cli/cmd-options#tls) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--tls-disable-host-verification** _bool_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Disable TLS host-name verification. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls-key-data** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--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. ## toggle -The `temporal schedule toggle` command can pause and unpause a [Schedule](/schedule). +Pause or unpause a Schedule by passing a flag with your desired state: + +``` +temporal schedule toggle \ + --schedule-id "YourScheduleId" \ + --pause \ + --reason "YourReason" +``` + +and + +``` +temporal schedule toggle + --schedule-id "YourScheduleId" \ + --unpause \ + --reason "YourReason" +``` + +The `--reason` text updates the Schedule's `notes` field for operations +communication. It defaults to "(no reason provided)" if omitted. This field is +also visible on the Service Web UI. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--pause** _bool_ + +Pause the Schedule. + +**--reason** _string_ + +Reason for pausing or unpausing the Schedule. (default "(no reason provided)") + +**--schedule-id**, **-s** _string_ -Toggling a Schedule requires a reason to be entered on the command line. -Use `--reason` to note the issue leading to the pause or unpause. +Schedule ID. Required. -Schedule toggles are passed in this format: -`temporal schedule toggle --schedule-id 'your-schedule-id' --pause --reason "paused because the database is down"` -`temporal schedule toggle --schedule-id 'your-schedule-id' --unpause --reason "the database is back up"` +**--unpause** _bool_ -Use the following options to change this command's behavior. +Unpause the Schedule. -- [--address](/cli/cmd-options#address) +**Global Flags:** -- [--codec-auth](/cli/cmd-options#codec-auth) +**--address** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--color](/cli/cmd-options#color) +**--api-key** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +API key for request. -- [--env](/cli/cmd-options#env) +**--codec-auth** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Authorization header for Codec Server requests. -- [--namespace](/cli/cmd-options#namespace) +**--codec-endpoint** _string_ -- [--pause](/cli/cmd-options#pause) +Remote Codec Server endpoint. -- [--reason](/cli/cmd-options#reason) +**--codec-header** _string[]_ -- [--schedule-id](/cli/cmd-options#schedule-id) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls](/cli/cmd-options#tls) +**--color** _string-enum_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--command-timeout** _duration_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +The command execution timeout. 0s means no timeout. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--env** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Active environment name (`ENV`). (default "default") -- [--unpause](/cli/cmd-options#unpause) +**--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. + +**--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") + +**--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. + +**--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. ## trigger -The `temporal schedule trigger` command triggers an immediate action with a given [Schedule](/schedule). -By default, this action is subject to the Overlap Policy of the Schedule. +Trigger a Schedule to run immediately: -Schedule triggers are passed in this format: -`temporal schedule trigger` can be used to start a Workflow Run immediately. -`temporal schedule trigger --schedule-id 'your-schedule-id'` +``` +temporal schedule trigger \ + --schedule-id "YourScheduleId" +``` -The Overlap Policy of the Schedule can be overridden as well. -`temporal schedule trigger --schedule-id 'your-schedule-id' --overlap-policy 'AllowAll'` +Use the following options to change the behavior of this command. -Use the following options to change this command's behavior. +**Flags:** -- [--address](/cli/cmd-options#address) +**--overlap-policy** _string-enum_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Policy for handling overlapping Workflow Executions. Accepted values: Skip, BufferOne, BufferAll, CancelOther, TerminateOther, AllowAll. (default "Skip") -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--schedule-id**, **-s** _string_ -- [--color](/cli/cmd-options#color) +Schedule ID. Required. -- [--command-timeout](/cli/cmd-options#command-timeout) +**Global Flags:** -- [--env](/cli/cmd-options#env) +**--address** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--namespace](/cli/cmd-options#namespace) +**--api-key** _string_ -- [--overlap-policy](/cli/cmd-options#overlap-policy) +API key for request. -- [--schedule-id](/cli/cmd-options#schedule-id) +**--codec-auth** _string_ -- [--tls](/cli/cmd-options#tls) +Authorization header for Codec Server requests. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--codec-endpoint** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Remote Codec Server endpoint. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--codec-header** _string[]_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--color** _string-enum_ -## update +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--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. + +**--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_ -The `temporal schedule update` command updates an existing [Schedule](/schedule). +Raw payload output, even if the JSON option was used. -Like `temporal schedule create`, updated Schedules need to follow a certain format: +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--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. + +**--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 + +Update an existing Schedule with new configuration details, including time +specifications, action, and policies: ``` -temporal schedule update \ - --schedule-id 'your-schedule-id' \ - --workflow-id 'your-workflow-id' \ - --task-queue 'your-task-queue' \ - --workflow-type 'YourWorkflowType' +temporal schedule update \ + --schedule-id "YourScheduleId" \ + --workflow-type "NewWorkflowType" ``` -Updating a Schedule takes the given options and replaces the entire configuration of the Schedule with what's provided. -If you only change one value of the Schedule, be sure to provide the other unchanged fields to prevent them from being overwritten. +Use the following options to change the behavior of this command. + +**Flags:** + +**--calendar** _string[]_ + +Calendar specification in JSON. For example: `{"dayOfWeek":"Fri","hour":"17","minute":"5"}`. + +**--catchup-window** _duration_ + +Maximum catch-up time for when the Service is unavailable. + +**--cron** _string[]_ + +Calendar specification in cron string format. For example: `"30 12 * * Fri"`. + +**--end-time** _timestamp_ + +Schedule end time. + +**--execution-timeout** _duration_ + +Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks. + +**--input**, **-i** _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** _bool_ + +Assume inputs are base64-encoded and attempt to decode them. + +**--input-file** _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** _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. + +**--interval** _string[]_ + +Interval duration. For example, 90m, or 60m/15m to include phase offset. + +**--jitter** _duration_ + +Max difference in time from the specification. Vary the start time randomly within this amount. + +**--memo** _string[]_ + +Memo using 'KEY="VALUE"' pairs. Use JSON values. + +**--notes** _string_ + +Initial notes field value. + +**--overlap-policy** _string-enum_ + +Policy for handling overlapping Workflow Executions. Accepted values: Skip, BufferOne, BufferAll, CancelOther, TerminateOther, AllowAll. (default "Skip") + +**--pause-on-failure** _bool_ + +Pause schedule after Workflow failures. + +**--paused** _bool_ + +Pause the Schedule immediately on creation. + +**--remaining-actions** _int_ + +Total allowed actions. Default is zero (unlimited). + +**--run-timeout** _duration_ + +Fail a Workflow Run if it lasts longer than `DURATION`. + +**--schedule-id**, **-s** _string_ + +Schedule ID. Required. + +**--schedule-memo** _string[]_ + +Set schedule memo using `KEY="VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--schedule-search-attribute** _string[]_ + +Set schedule Search Attributes using `KEY="VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--search-attribute** _string[]_ + +Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--start-time** _timestamp_ + +Schedule start time. + +**--static-details** _string_ + +Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines. + +:::note + +Option is experimental. + +::: + +**--static-summary** _string_ + +Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line. + +:::note + +Option is experimental. + +::: + +**--task-queue**, **-t** _string_ + +Workflow Task queue. Required. + +**--task-timeout** _duration_ + +Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s") + +**--time-zone** _string_ + +Interpret calendar specs with the `TZ` time zone. For a list of time zones, see: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. + +**--type** _string_ + +Workflow Type name. Required. + +**--workflow-id**, **-w** _string_ + +Workflow ID. If not supplied, the Service generates a unique ID. + +**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. -Use the following options to change the command's behavior. +**--color** _string-enum_ -- [--address](/cli/cmd-options#address) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--calendar](/cli/cmd-options#calendar) +**--command-timeout** _duration_ -- [--catchup-window](/cli/cmd-options#catchup-window) +The command execution timeout. 0s means no timeout. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--env** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Active environment name (`ENV`). (default "default") -- [--color](/cli/cmd-options#color) +**--env-file** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--cron](/cli/cmd-options#cron) +**--grpc-meta** _string[]_ -- [--end-time](/cli/cmd-options#end-time) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--env](/cli/cmd-options#env) +**--log-format** _string-enum_ -- [--execution-timeout](/cli/cmd-options#execution-timeout) +Log format. Accepted values: text, json. (default "text") -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--log-level** _string-enum_ -- [--input](/cli/cmd-options#input) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--input-file](/cli/cmd-options#input-file) +**--namespace**, **-n** _string_ -- [--interval](/cli/cmd-options#interval) +Temporal Service Namespace. (default "default") -- [--jitter](/cli/cmd-options#jitter) +**--no-json-shorthand-payloads** _bool_ -- [--max-field-length](/cli/cmd-options#max-field-length) +Raw payload output, even if the JSON option was used. -- [--memo](/cli/cmd-options#memo) +**--output**, **-o** _string-enum_ -- [--memo-file](/cli/cmd-options#memo-file) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--namespace](/cli/cmd-options#namespace) +**--time-format** _string-enum_ -- [--notes](/cli/cmd-options#notes) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--overlap-policy](/cli/cmd-options#overlap-policy) +**--tls** _bool_ -- [--pause](/cli/cmd-options#pause) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--pause-on-failure](/cli/cmd-options#pause-on-failure) +**--tls-ca-data** _string_ -- [--remaining-actions](/cli/cmd-options#remaining-actions) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--run-timeout](/cli/cmd-options#run-timeout) +**--tls-ca-path** _string_ -- [--schedule-id](/cli/cmd-options#schedule-id) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--search-attribute](/cli/cmd-options#search-attribute) +**--tls-cert-data** _string_ -- [--start-time](/cli/cmd-options#start-time) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--task-queue](/cli/cmd-options#task-queue) +**--tls-cert-path** _string_ -- [--task-timeout](/cli/cmd-options#task-timeout) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--time-zone](/cli/cmd-options#time-zone) +**--tls-disable-host-verification** _bool_ -- [--tls](/cli/cmd-options#tls) +Disable TLS host-name verification. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--tls-key-data** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls-key-path** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--tls-server-name** _string_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Override target TLS server name. -- [--workflow-type](/cli/cmd-options#workflow-type) diff --git a/docs/cli/server.mdx b/docs/cli/server.mdx index 6593e52e64..9a2b9e877c 100644 --- a/docs/cli/server.mdx +++ b/docs/cli/server.mdx @@ -1,7 +1,7 @@ --- id: server -title: Temporal CLI server command reference -sidebar_label: server +title: temporal server +sidebar_label: temporal server description: Manage your Temporal Server easily with CLI commands. Start a local server using `temporal server start-dev` and access the Web UI at http://localhost:8233. Customize with multiple options. toc_max_heading_level: 4 keywords: @@ -11,46 +11,220 @@ keywords: - server start-dev - temporal cli tags: - - Temporal CLI - - Development Server + - cli-reference + - command-line-interface-cli + - server + - server-start-dev + - temporal-cli --- -Server commands allow you to start and manage the [Temporal Server](/temporal-service/temporal-server) from the command line. +## start-dev + +Run a development Temporal Server on your local system. -Currently, `cli` server functionality extends to starting the Server. ++------------------------------------------------------------------------+ +| WARNING: The development server is not intended for production use. | +| It skips certain HTTP security checks to make local use simpler. | +| | +| For production use, see: | +| https://docs.temporal.io/production-deployment | ++------------------------------------------------------------------------+ -## start-dev +View the Web UI for the default configuration at: http://localhost:8233 + +``` +temporal server start-dev +``` + +Add persistence for Workflow Executions across runs: + +``` +temporal server start-dev \ + --db-filename path-to-your-local-persistent-store +``` + +Set the port from the front-end gRPC Service (7233 default): + +``` +temporal server start-dev \ + --port 7000 +``` + +Use a custom port for the Web UI. The default is the gRPC port (7233 default) +plus 1000 (8233): -The `temporal server start-dev` command starts a local [Temporal Server](/temporal-service/temporal-server). -You can access the Web UI at http://localhost:8233. -The default Frontend Service gRPC port used as a target endpoint for client calls is 7233. +``` +temporal server start-dev \ + --ui-port 3000 +``` Use the following options to change the behavior of this command. -- [--db-filename](/cli/cmd-options#db-filename) +**Flags:** + +**--db-filename**, **-f** _string_ + +Path to file for persistent Temporal state store. By default, Workflow Executions are lost when the server process dies. + +**--dynamic-config-value** _string[]_ + +Dynamic configuration value using `KEY=VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: 'YourKey="YourString"'. Can be passed multiple times. + +**--headless** _bool_ + +Disable the Web UI. + +**--http-port** _int_ + +Port for the HTTP API service. Defaults to a random free port. (default "0") + +**--ip** _string_ + +IP address bound to the front-end Service. (default "localhost") + +**--log-config** _bool_ + +Log the server config to stderr. + +**--metrics-port** _int_ + +Port for '/metrics'. Default is off. + +**--namespace**, **-n** _string[]_ + +Namespaces to be created at launch. The "default" Namespace is always created automatically. + +**--port**, **-p** _int_ + +Port for the front-end gRPC Service. (default "7233") + +**--search-attribute** _string[]_ + +Search attributes to register using `KEY=VALUE` pairs. Keys must be identifiers, and values must be the search attribute type, which is one of the following: Text, Keyword, Int, Double, Bool, Datetime, KeywordList. + +**--sqlite-pragma** _string[]_ + +SQLite pragma statements in "PRAGMA=VALUE" format. + +**--ui-asset-path** _string_ + +UI custom assets path. + +**--ui-codec-endpoint** _string_ + +UI remote codec HTTP endpoint. + +**--ui-ip** _string_ + +IP address bound to the Web UI. Default is same as '--ip' value. + +**--ui-port** _int_ + +Port for the Web UI. Default is '--port' value + 1000. + +**--ui-public-path** _string_ + +The public base path for the Web UI. Default is `/`. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. -- [--dynamic-config-value](/cli/cmd-options#dynamic-config-value) +**--tls-cert-data** _string_ -- [--headless](/cli/cmd-options#headless) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--ip](/cli/cmd-options#ip) +**--tls-cert-path** _string_ -- [--log-format](/cli/cmd-options#log-format) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--log-level](/cli/cmd-options#log-level) +**--tls-disable-host-verification** _bool_ -- [--metrics-port](/cli/cmd-options#metrics-port) +Disable TLS host-name verification. -- [--namespace](/cli/cmd-options#namespace) +**--tls-key-data** _string_ -- [--port](/cli/cmd-options#port) +Private certificate key data. Can't be used with --tls-key-path. -- [--sqlite-pragma](/cli/cmd-options#sqlite-pragma) +**--tls-key-path** _string_ -- [--ui-asset-path](/cli/cmd-options#ui-asset-path) +Path to x509 private key. Can't be used with --tls-key-data. -- [--ui-codec-endpoint](/cli/cmd-options#ui-codec-endpoint) +**--tls-server-name** _string_ -- [--ui-ip](/cli/cmd-options#ui-ip) +Override target TLS server name. -- [--ui-port](/cli/cmd-options#ui-port) diff --git a/docs/cli/task-queue.mdx b/docs/cli/task-queue.mdx index cf7513b74a..8a26097c0a 100644 --- a/docs/cli/task-queue.mdx +++ b/docs/cli/task-queue.mdx @@ -1,7 +1,7 @@ --- id: task-queue -title: Temporal CLI task-queue command reference -sidebar_label: task-queue +title: temporal task-queue +sidebar_label: temporal task-queue description: Temporal Task Queue commands facilitate operations like describing poller info, displaying partitions, fetching compatible Build IDs, and determining Build ID reachability for effective Workflow and Activity management. toc_max_heading_level: 4 keywords: @@ -12,180 +12,2314 @@ keywords: - task queue describe - temporal cli tags: - - Temporal CLI + - cli-reference + - command-line-interface-cli + - list-partitions + - task-queue + - task-queue-describe + - temporal-cli --- -Task Queue commands allow operations to be performed on [Task Queues](/task-queue). -To run a Task Queue command, run `temporal task-queue [command] [command options]` - ## describe -The `temporal task-queue describe` command provides [poller](/develop/worker-performance#poller-count) information for a given [Task Queue](/task-queue). +Display a list of active Workers that have recently polled a Task Queue. The +Temporal Server records each poll request time. A `LastAccessTime` over one +minute may indicate the Worker is at capacity or has shut down. Temporal +Workers are removed if 5 minutes have passed since the last poll request. + +``` +temporal task-queue describe \ + --task-queue YourTaskQueue +``` + +This command provides poller information for a given Task Queue. +Workflow and Activity polling use separate Task Queues: + +``` +temporal task-queue describe \ + --task-queue YourTaskQueue \ + --task-queue-type "activity" +``` + +This command provides the following task queue statistics: +- `ApproximateBacklogCount`: The approximate number of tasks backlogged in this + task queue. May count expired tasks but eventually converges to the right + value. +- `ApproximateBacklogAge`: Approximate age of the oldest task in the backlog, + based on its creation time, measured in seconds. +- `TasksAddRate`: Approximate rate at which tasks are being added to the task + queue, measured in tasks per second, averaged over the last 30 seconds. + Includes tasks dispatched immediately without going to the backlog + (sync-matched tasks), as well as tasks added to the backlog. (See note below.) +- `TasksDispatchRate`: Approximate rate at which tasks are being dispatched from + the task queue, measured in tasks per second, averaged over the last 30 + seconds. Includes tasks dispatched immediately without going to the backlog + (sync-matched tasks), as well as tasks added to the backlog. (See note below.) +- `BacklogIncreaseRate`: Approximate rate at which the backlog size is + increasing (if positive) or decreasing (if negative), measured in tasks per + second, averaged over the last 30 seconds. This is roughly equivalent to: + `TasksAddRate` - `TasksDispatchRate`. + +NOTE: The `TasksAddRate` and `TasksDispatchRate` metrics may differ from the +actual rate of add/dispatch, because tasks may be dispatched eagerly to an +available worker, or may apply only to specific workers (they are "sticky"). +Such tasks are not counted by these metrics. Despite the inaccuracy of +these two metrics, the derived metric of `BacklogIncreaseRate` is accurate +for backlogs older than a few seconds. + +Safely retire Workers assigned a Build ID by checking reachability across +all task types. Use the flag `--report-reachability`: + +``` +temporal task-queue describe \ + --task-queue YourTaskQueue \ + --build-id "YourBuildId" \ + --report-reachability +``` + +Task reachability information is returned for the requested versions and all +task types, which can be used to safely retire Workers with old code versions, +provided that they were assigned a Build ID. + +Note that task reachability status is experimental and may significantly change +or be removed in a future release. Also, determining task reachability incurs a +non-trivial computing cost. + +Task reachability states are reported per build ID. The state may be one of the +following: + +- `Reachable`: using the current versioning rules, the Build ID may be used + by new Workflow Executions or Activities OR there are currently open + Workflow or backlogged Activity tasks assigned to the queue. +- `ClosedWorkflowsOnly`: the Build ID does not have open Workflow Executions + and can't be reached by new Workflow Executions. It MAY have closed + Workflow Executions within the Namespace retention period. +- `Unreachable`: this Build ID is not used for new Workflow Executions and + isn't used by any existing Workflow Execution within the retention period. + +Task reachability is eventually consistent. You may experience a delay until +reachability converges to the most accurate value. This is designed to act +in the most conservative way until convergence. For example, `Reachable` is +more conservative than `ClosedWorkflowsOnly`. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--disable-stats** _bool_ + +Disable task queue statistics. + +**--legacy-mode** _bool_ + +Enable a legacy mode for servers that do not support rules-based worker versioning. This mode only provides pollers info. + +**--partitions-legacy** _int_ + +Query partitions 1 through `N`. Experimental/Temporary feature. Legacy mode only. (default "1") + +**--report-reachability** _bool_ + +Display task reachability information. + +**--select-all-active** _bool_ + +Include all active versions. A version is active if it had new tasks or polls recently. + +**--select-build-id** _string[]_ + +Filter the Task Queue based on Build ID. + +**--select-unversioned** _bool_ + +Include the unversioned queue. + +**--task-queue**, **-t** _string_ + +Task Queue name. Required. + +**--task-queue-type** _string-enum[]_ + +Task Queue type. If not specified, all types are reported. Accepted values: workflow, activity, nexus. + +**--task-queue-type-legacy** _string-enum_ + +Task Queue type (legacy mode only). Accepted values: workflow, activity. (default "workflow") + +**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. + +**--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. + +**--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") + +**--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. + +**--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. -The [Server](/temporal-service/temporal-server) records the last time of each poll request. -A `LastAccessTime` value in excess of one minute can indicate the Worker is at capacity (all Workflow and Activity slots are full) or that the Worker has shut down. -[Workers](/workers#worker) are removed if 5 minutes have passed since the last poll request. +**--tls-cert-data** _string_ -Information about the Task Queue can be returned to troubleshoot server issues. +Data for x509 certificate. Can't be used with --tls-cert-path. -`temporal task-queue describe --task-queue=MyTaskQueue --task-queue-type="activity"` +**--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. + +## get-build-id-reachability + ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ + +Show if a given Build ID can be used for new, existing, or closed Workflows +in Namespaces that support Worker versioning: + +``` +temporal task-queue get-build-id-reachability \ + --task-queue YourTaskQueue \ + --build-id "YourBuildId" +``` + +You can specify the `--build-id` and `--task-queue` flags multiple times. If +`--task-queue` is omitted, the command checks Build ID reachability against +all Task Queues. Use the following options to change the behavior of this command. -- [--fields](/cli/cmd-options#fields) -- [--address](/cli/cmd-options#address) +**Flags:** -- [--codec-auth](/cli/cmd-options#codec-auth) +**--build-id** _string[]_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +One or more Build ID strings. Can be passed multiple times. -- [--color](/cli/cmd-options#color) +**--reachability-type** _string-enum_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Reachability filter. `open`: reachable by one or more open workflows. `closed`: reachable by one or more closed workflows. `existing`: reachable by either. New Workflow Executions reachable by a Build ID are always reported. Accepted values: open, closed, existing. (default "existing") -- [--env](/cli/cmd-options#env) +**--task-queue**, **-t** _string[]_ -- [--fields](/cli/cmd-options#fields) +Search only the specified task queue(s). Can be passed multiple times. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**Global Flags:** -- [--namespace](/cli/cmd-options#namespace) +**--address** _string_ -- [--output](/cli/cmd-options#output) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--task-queue](/cli/cmd-options#task-queue) +**--api-key** _string_ -- [--task-queue-type](/cli/cmd-options#task-queue-type) +API key for request. -- [--time-format](/cli/cmd-options#time-format) +**--codec-auth** _string_ -- [--tls](/cli/cmd-options#tls) +Authorization header for Codec Server requests. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--codec-endpoint** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Remote Codec Server endpoint. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--codec-header** _string[]_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--color** _string-enum_ -## list-partition +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--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. + +**--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. -The `temporal task-queue list-partition` command displays the partitions of a [Task Queue](/task-queue), along with the matching node they are assigned to. +**--output**, **-o** _string-enum_ -Use the following options to change the command's behavior. +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--address](/cli/cmd-options#address) +**--time-format** _string-enum_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--tls** _bool_ -- [--color](/cli/cmd-options#color) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--tls-ca-data** _string_ -- [--env](/cli/cmd-options#env) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--tls-ca-path** _string_ -- [--namespace](/cli/cmd-options#namespace) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--output](/cli/cmd-options#output) +**--tls-cert-data** _string_ -- [--task-queue](/cli/cmd-options#task-queue) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--tls](/cli/cmd-options#tls) +**--tls-cert-path** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--tls-disable-host-verification** _bool_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Disable TLS host-name verification. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--tls-key-data** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +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. ## get-build-ids -Fetch the sets of compatible build IDs associated with a Task Queue and associated information. ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ -- [--address](/cli/cmd-options#address) +Fetch sets of compatible Build IDs for specified Task Queues and display their +information: -- [--codec-auth](/cli/cmd-options#codec-auth) +``` +temporal task-queue get-build-ids \ + --task-queue YourTaskQueue +``` -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +This command is limited to Namespaces that support Worker versioning. -- [--color](/cli/cmd-options#color) +Use the following options to change the behavior of this command. -- [--command-timeout](/cli/cmd-options#command-timeout) +**Flags:** -- [--env](/cli/cmd-options#env) +**--max-sets** _int_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Max return count. Use 1 for default major version. Use 0 for all sets. (default "0") -- [--max-sets](/cli/cmd-options#max-sets) +**--task-queue**, **-t** _string_ -- [--namespace](/cli/cmd-options#namespace) +Task Queue name. Required. -- [--task-queue](/cli/cmd-options#task-queue) +**Global Flags:** -- [--tls](/cli/cmd-options#tls) +**--address** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--api-key** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +API key for request. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--codec-auth** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Authorization header for Codec Server requests. -## get-build-id-reachability +**--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. + +**--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. + +**--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") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ -Determines whether Build IDs can be used for new, existing, or closed Workflows. -Both the `--build-id` and `--task-queue` options can be specified multiple times. -If a Task Queue isn't provided, reachability for the provided Build IDs is checked against all Task Queues. +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--address](/cli/cmd-options#address) +**--tls-ca-data** _string_ -- [--build-id](/cli/cmd-options#build-id) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--tls-ca-path** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--color](/cli/cmd-options#color) +**--tls-cert-data** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--env](/cli/cmd-options#env) +**--tls-cert-path** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--namespace](/cli/cmd-options#namespace) +**--tls-disable-host-verification** _bool_ -- [--reachability-type](/cli/cmd-options#reachability-type) +Disable TLS host-name verification. -- [--task-queue](/cli/cmd-options#task-queue) +**--tls-key-data** _string_ -- [--tls](/cli/cmd-options#tls) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--tls-key-path** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls-server-name** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Override target TLS server name. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +## list-partition + +Display a Task Queue's partition list with assigned matching nodes: + +``` +temporal task-queue list-partition \ + --task-queue YourTaskQueue +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--task-queue**, **-t** _string_ + +Task Queue name. 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. + +**--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. + +**--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") + +**--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. + +**--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-build-ids -Provides various commands for adding or changing the sets of compatible build IDs associated with a Task Queue. -See the help text provided for each sub-command for more. ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ + +Add or change a Task Queue's compatible Build IDs for Namespaces using Worker +versioning: + +``` +temporal task-queue update-build-ids [subcommands] [options] \ + --task-queue YourTaskQueue +``` + +### add-new-compatible + +Add a compatible Build ID to a Task Queue's existing version set. Provide an +existing Build ID and a new Build ID: + +``` +temporal task-queue update-build-ids add-new-compatible \ + --task-queue YourTaskQueue \ + --existing-compatible-build-id "YourExistingBuildId" \ + --build-id "YourNewBuildId" +``` + +The new ID is stored in the set containing the existing ID and becomes the new +default for that set. + +This command is limited to Namespaces that support Worker versioning. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--build-id** _string_ + +Build ID to be added. Required. + +**--existing-compatible-build-id** _string_ + +Pre-existing Build ID in this Task Queue. Required. + +**--set-as-default** _bool_ + +Set the expanded Build ID set as the Task Queue default. + +**--task-queue**, **-t** _string_ + +Task Queue name. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +### add-new-default + ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ + +Create a new Task Queue Build ID set, add a Build ID to it, and make it the +overall Task Queue default. The new set will be incompatible with previous +sets and versions. + +``` +temporal task-queue update-build-ids add-new-default \ + --task-queue YourTaskQueue \ + --build-id "YourNewBuildId" +``` + ++------------------------------------------------------------------------+ +| NOTICE: This command is limited to Namespaces that support Worker | +| versioning. Worker versioning is experimental. Versioning commands are | +| subject to change. | ++------------------------------------------------------------------------+ + +Use the following options to change the behavior of this command. + +**Flags:** + +**--build-id** _string_ + +Build ID to be added. Required. + +**--task-queue**, **-t** _string_ + +Task Queue name. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +### promote-id-in-set + ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ + +Establish an existing Build ID as the default in its Task Queue set. New tasks +compatible with this set will now be dispatched to this ID: + +``` +temporal task-queue update-build-ids promote-id-in-set \ + --task-queue YourTaskQueue \ + --build-id "YourBuildId" +``` + ++------------------------------------------------------------------------+ +| NOTICE: This command is limited to Namespaces that support Worker | +| versioning. Worker versioning is experimental. Versioning commands are | +| subject to change. | ++------------------------------------------------------------------------+ + +Use the following options to change the behavior of this command. + +**Flags:** + +**--build-id** _string_ + +Build ID to set as default. Required. + +**--task-queue**, **-t** _string_ + +Task Queue name. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +### promote-set + ++-----------------------------------------------------------------------------+ +| CAUTION: This command is deprecated and will be removed in a later release. | ++-----------------------------------------------------------------------------+ + +Promote a Build ID set to be the default on a Task Queue. Identify the set by +providing a Build ID within it. If the set is already the default, this +command has no effect: + +``` +temporal task-queue update-build-ids promote-set \ + --task-queue YourTaskQueue \ + --build-id "YourBuildId" +``` + ++------------------------------------------------------------------------+ +| NOTICE: This command is limited to Namespaces that support Worker | +| versioning. Worker versioning is experimental. Versioning commands are | +| subject to change. | ++------------------------------------------------------------------------+ + +Use the following options to change the behavior of this command. + +**Flags:** + +**--build-id** _string_ + +Build ID within the promoted set. Required. + +**--task-queue**, **-t** _string_ + +Task Queue name. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +## versioning + ++---------------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++---------------------------------------------------------------------+ + +Provides commands to add, list, remove, or replace Worker Build ID assignment +and redirect rules associated with Task Queues: + +``` +temporal task-queue versioning [subcommands] [options] \ + --task-queue YourTaskQueue +``` + +Task Queues support the following versioning rules and policies: + +- Assignment Rules: manage how new executions are assigned to run on specific + Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules, + which are evaluated from first to last. Assignment Rules also allow for + gradual rollout of new Build IDs by setting ramp percentage. +- Redirect Rules: automatically assign work for a source Build ID to a target + Build ID. You may add at most one redirect rule for each source Build ID. + Redirect rules require that a target Build ID is fully compatible with + the source Build ID. + +### add-redirect-rule + +Add a new redirect rule for a given Task Queue. You may add at most one +redirect rule for each distinct source build ID: + +``` +temporal task-queue versioning add-redirect-rule \ + --task-queue YourTaskQueue \ + --source-build-id "YourSourceBuildID" \ + --target-build-id "YourTargetBuildID" +``` + ++---------------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++---------------------------------------------------------------------+ + +Use the following options to change the behavior of this command. + +**Flags:** + +**--source-build-id** _string_ + +Source build ID. Required. + +**--target-build-id** _string_ + +Target build ID. Required. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +### commit-build-id + +Complete a Build ID's rollout and clean up unnecessary rules that might have +been created during a gradual rollout: + +``` +temporal task-queue versioning commit-build-id \ + --task-queue YourTaskQueue + --build-id "YourBuildId" +``` + +This command automatically applies the following atomic changes: + +- Adds an unconditional assignment rule for the target Build ID at the + end of the list. +- Removes all previously added assignment rules to the given target + Build ID. +- Removes any unconditional assignment rules for other Build IDs. + +Rejects requests when there have been no recent pollers for this Build ID. +This prevents committing invalid Build IDs. Use the `--force` option to +override this validation. + ++---------------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++---------------------------------------------------------------------+ + +Use the following options to change the behavior of this command. + +**Flags:** + +**--build-id** _string_ + +Target build ID. Required. + +**--force** _bool_ + +Bypass recent-poller validation. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +### delete-assignment-rule + +Deletes a rule identified by its index in the Task Queue's list of assignment +rules. + +``` +temporal task-queue versioning delete-assignment-rule \ + --task-queue YourTaskQueue \ + --rule-index YourIntegerRuleIndex +``` + +By default, the Task Queue must retain one unconditional rule, such as "no +hint filter" or "percentage". Otherwise, the delete operation is rejected. +Use the `--force` option to override this validation. + ++---------------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++---------------------------------------------------------------------+ + +Use the following options to change the behavior of this command. + +**Flags:** + +**--force** _bool_ + +Bypass one-unconditional-rule validation. + +**--rule-index**, **-i** _int_ + +Position of the assignment rule to be replaced. Requests for invalid indices will fail. Required. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +### delete-redirect-rule + +Deletes the routing rule for the given source Build ID. + +``` +temporal task-queue versioning delete-redirect-rule \ + --task-queue YourTaskQueue \ + --source-build-id "YourBuildId" +``` + ++---------------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++---------------------------------------------------------------------+ + +Use the following options to change the behavior of this command. + +**Flags:** + +**--source-build-id** _string_ + +Source Build ID. Required. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +### get-rules + +Retrieve all the Worker Build ID assignments and redirect rules associated +with a Task Queue: + +``` +temporal task-queue versioning get-rules \ + --task-queue YourTaskQueue +``` + +Task Queues support the following versioning rules: + +- Assignment Rules: manage how new executions are assigned to run on specific + Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules, + which are evaluated from first to last. Assignment Rules also allow for + gradual rollout of new Build IDs by setting ramp percentage. +- Redirect Rules: automatically assign work for a source Build ID to a target + Build ID. You may add at most one redirect rule for each source Build ID. + Redirect rules require that a target Build ID is fully compatible with + the source Build ID. ++---------------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++---------------------------------------------------------------------+ + +Use the following options to change the behavior of this command. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +### insert-assignment-rule + +Inserts a new assignment rule for this Task Queue. Rules are evaluated in +order, starting from index 0. The first applicable rule is applied, and the +rest ignored: + +``` +temporal task-queue versioning insert-assignment-rule \ + --task-queue YourTaskQueue \ + --build-id "YourBuildId" +``` + +If you do not specify a `--rule-index`, this command inserts at index 0. + ++---------------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++---------------------------------------------------------------------+ + +Use the following options to change the behavior of this command. + +**Flags:** + +**--build-id** _string_ + +Target Build ID. Required. + +**--percentage** _int_ + +Traffic percent to send to target Build ID. (default "100") + +**--rule-index**, **-i** _int_ + +Insertion position. Ranges from 0 (insert at start) to count (append). Any number greater than the count is treated as "append". (default "0") + +**--yes**, **-y** _bool_ + +Don't prompt to confirm. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +### replace-assignment-rule + +Change an assignment rule for this Task Queue. By default, this enforces one +unconditional rule (no hint filter or percentage). Otherwise, the operation +will be rejected. Set `force` to true to bypass this validation. + +``` +temporal task-queue versioning replace-assignment-rule \ + --task-queue YourTaskQueue \ + --rule-index AnIntegerIndex \ + --build-id "YourBuildId" +``` + +To assign multiple assignment rules to a single Build ID, use +'insert-assignment-rule'. + +To update the percent: + +``` +temporal task-queue versioning replace-assignment-rule \ + --task-queue YourTaskQueue \ + --rule-index AnIntegerIndex \ + --build-id "YourBuildId" \ + --percentage AnIntegerPercent +``` + +Percent may vary between 0 and 100 (default). + ++---------------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++---------------------------------------------------------------------+ + +Use the following options to change the behavior of this command. + +**Flags:** + +**--build-id** _string_ + +Target Build ID. Required. + +**--force** _bool_ + +Bypass the validation that one unconditional rule remains. + +**--percentage** _int_ + +Divert percent of traffic to target Build ID. (default "100") + +**--rule-index**, **-i** _int_ + +Position of the assignment rule to be replaced. Requests for invalid indices will fail. Required. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +### replace-redirect-rule + +Updates a Build ID's redirect rule on a Task Queue by replacing its target +Build ID: + +``` +temporal task-queue versioning replace-redirect-rule \ + --task-queue YourTaskQueue \ + --source-build-id YourSourceBuildId \ + --target-build-id YourNewTargetBuildId +``` + ++---------------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++---------------------------------------------------------------------+ + +Use the following options to change the behavior of this command. + +**Flags:** + +**--source-build-id** _string_ + +Source Build ID. Required. + +**--target-build-id** _string_ + +Target Build ID. Required. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + diff --git a/docs/cli/worker.mdx b/docs/cli/worker.mdx new file mode 100644 index 0000000000..59777d8a51 --- /dev/null +++ b/docs/cli/worker.mdx @@ -0,0 +1,1217 @@ +--- +id: worker +title: temporal worker +sidebar_label: temporal worker +description: Learn how to read or modify state associated with a Worker, such as Worker Deployments. +toc_max_heading_level: 4 +keywords: + - worker + - worker deployment +tags: + - worker + - worker-deployment +--- + +## deployment + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Deployment commands perform operations on Worker Deployments: + +``` +temporal worker deployment [command] [options] +``` + +For example: + +``` +temporal worker deployment list +``` + +Lists the Deployments in the client's namespace. + +Arguments can be Worker Deployment Versions associated with +a Deployment, using a fully qualified Version identifier that +concatenates the Deployment Name and the Build ID with the +reserved separator ".". + +For example: + +``` +temporal worker deployment set-current-version \ + --version YourDeploymentName.YourBuildID +``` + +Sets the current Deployment Version for a given Deployment. + +### delete + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Remove a Worker Deployment given its Deployment Name. +A Deployment can only be deleted if it has no Version in it. + +``` +temporal worker deployment delete [options] +``` + +For example, setting the user identity that removed the deployment: + +``` +temporal worker deployment delete \ + --name YourDeploymentName \ + --identity YourIdentity + +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--identity** _string_ + +Identity of the user submitting this request. + +**--name**, **-d** _string_ + +Name for a Worker Deployment. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +### delete-version + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Remove a Worker Deployment Version given its fully-qualified identifier. +This is rarely needed during normal operation +since unused Versions are eventually garbage collected. +The client can delete a Version only when all of the following conditions +are met: + - It is not the Current or Ramping Version for this Deployment. + - It has no active pollers, i.e., none of the task queues in the + Version have pollers. + - It is not draining. This requirement can be ignored with the option +`--skip-drainage`. + +``` +temporal worker deployment delete-version [options] +``` + +For example, skipping the drainage restriction: + +``` +temporal worker deployment delete-version \ + --version YourDeploymentName.YourBuildID \ + --skip-drainage +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--identity** _string_ + +Identity of the user submitting this request. + +**--skip-drainage** _bool_ + +Ignore the deletion requirement of not draining. + +**--version**, **-v** _string_ + +Fully-qualified name for a Worker Deployment Version. Use the format `YourDeploymentName.YourBuildID`. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +### describe + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Describe properties of a Worker Deployment, such as the versions +associated with it, routing information of new or existing tasks +executed by this deployment, or its creation time. + +``` +temporal worker deployment describe [options] +``` + +For example, to describe a deployment `YourDeploymentName` in the default +namespace: + +``` +temporal worker deployment describe \ + --name YourDeploymentName +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--name**, **-d** _string_ + +Name for a Worker Deployment. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +### describe-version + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Describe properties of a Worker Deployment Version, such as the task +queues polled by workers in this Deployment Version, or drainage +information required to safely decommission workers, or user-provided +metadata, or its creation/modification time. + +``` +temporal worker deployment describe-version [options] +``` + +For example, to describe a deployment version in a deployment +`YourDeploymentName`, with Build ID `YourBuildID`, and in the default +namespace: + +``` +temporal worker deployment describe-version \ + --version YourDeploymentName.YourBuildID +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--version**, **-v** _string_ + +Fully-qualified name for a Worker Deployment Version. Use the format `YourDeploymentName.YourBuildID`. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +### list + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +List existing Worker Deployments in the client's namespace. + +``` +temporal worker deployment list [options] +``` + +For example, listing Deployments in YourDeploymentNamespace: + +``` +temporal worker deployment list \ + --namespace YourDeploymentNamespace +``` + +Use the following options to change the behavior of this command. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +### set-current-version + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Set the Current Version for a Deployment. +When a Version is current, Workers of that Deployment Version will receive +tasks from new Workflows, and from existing AutoUpgrade Workflows that +are running on this Deployment. + +If not all the expected Task Queues are being polled by Workers in the +new Version the request will fail. To override this protection use +`--ignore-missing-task-queues`. Note that this would ignore task queues +in a deployment that are not yet discovered, leading to inconsistent task +queue configuration. + +``` +temporal worker deployment set-current-version [options] +``` + +For example, to set the Current Version of a deployment +`YourDeploymentName`, with a version with Build ID `YourBuildID`, and +in the default namespace: + +``` +temporal worker deployment set-current-version \ + --version YourDeploymentName.YourBuildID +``` + +The target of set-current-version can also be `__unversioned__`, which +moves tasks to unversioned workers, but in this case we also need to +specify the Deployment Name. + +``` +temporal worker deployment set-current-version \ + --version __unversioned__ \ + --deployment-name YourDeploymentName +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--deployment-name** _string_ + +Deployment name. Only needed when `--version` is `__unversioned__` or empty. + +**--identity** _string_ + +Identity of the user submitting this request. + +**--ignore-missing-task-queues** _bool_ + +Override protection to accidentally remove task queues. + +**--version**, **-v** _string_ + +Fully-qualified name for a Worker Deployment Version. Use the format `YourDeploymentName.YourBuildID`. Required. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm set Current Version. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +### set-ramping-version + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Set the Ramping Version and Percentage for a Deployment. + +The Ramping Version can be set to a fully-qualified Version of the form +`YourDeploymentName.YourBuildID`, or set to "__unversioned__", a special +value that represents all the unversioned workers. + +The Ramping Percentage is a float with values in the range [0, 100]. +A value of 100 does not make the Ramping Version Current, use +`set-current-version` instead. + +To remove a Ramping Version use the flag `--delete`. + +If not all the expected Task Queues are being polled by Workers in the +new Ramping Version the request will fail. To override this protection use +`--ignore-missing-task-queues`. Note that this would ignore task queues +in a deployment that are not yet discovered, leading to inconsistent task +queue configuration. + +``` +temporal worker deployment set-ramping-version [options] +``` + +For example, to set the Ramping Version of a deployment +`YourDeploymentName`, with a version with Build ID `YourBuildID`, with +10 percent of tasks redirected to this version, and +using the default namespace: + +``` +temporal worker deployment set-ramping-version \ + --version YourDeploymentName.YourBuildID + --percentage 10.0 +``` + +And to remove that ramping: + +``` +temporal worker deployment set-ramping-version \ + --version YourDeploymentName.YourBuildID \ + --delete +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--delete** _bool_ + +Delete the Ramping Version. + +**--deployment-name** _string_ + +Deployment name. Only needed when `--version` is `__unversioned__`. + +**--identity** _string_ + +Identity of the user submitting this request. + +**--ignore-missing-task-queues** _bool_ + +Override protection to accidentally remove task queues. + +**--percentage** _float_ + +Percentage of tasks redirected to the Ramping Version. Valid range [0,100]. + +**--version**, **-v** _string_ + +Fully-qualified name for a Worker Deployment Version. Use the format `YourDeploymentName.YourBuildID`. Required. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm set Ramping Version. + +**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. + +**--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. + +**--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") + +**--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. + +**--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-metadata-version + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ +Update metadata associated with a Worker Deployment Version. + +For example: + +``` + temporal worker deployment update-metadata-version \ + --version YourDeploymentName.YourBuildID \ + --metadata bar=1 \ + --metadata foo=true +``` + +The current metadata is also returned with `describe-version`: + +``` + temporal worker deployment describe-version \ + --version YourDeploymentName.YourBuildID \ +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--metadata** _string[]_ + +Set deployment metadata using `KEY="VALUE"` pairs. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--remove-entries** _string[]_ + +Keys of entries to be deleted from metadata. Can be passed multiple times. + +**--version**, **-v** _string_ + +Fully-qualified name for a Worker Deployment Version. Use the format `YourDeploymentName.YourBuildID`. 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. + +**--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. + +**--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") + +**--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. + +**--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. + diff --git a/docs/cli/workflow.mdx b/docs/cli/workflow.mdx index faeb6cd13a..6eceeb9c76 100644 --- a/docs/cli/workflow.mdx +++ b/docs/cli/workflow.mdx @@ -1,8 +1,8 @@ --- id: workflow -title: Temporal CLI workflow command reference -sidebar_label: workflow -description: Temporal Workflow commands enable operations on Workflow Executions, such as cancel, count, delete, describe, execute, list, query, reset, reset-batch, show, signal, stack, start, terminate, trace, and update, enhancing efficiency and control. +title: temporal workflow +sidebar_label: temporal workflow +description: Temporal Workflow commands enable operations on Workflow Executions, such as cancel, count, delete, describe, execute, list, update-options, query, reset, reset-batch, show, signal, stack, start, terminate, trace, and update, enhancing efficiency and control. toc_max_heading_level: 4 keywords: - call stack @@ -26,6 +26,7 @@ keywords: - workflow execute - workflow execution - workflow list + - workflow metadata - workflow query - workflow reset - workflow reset-batch @@ -35,876 +36,3598 @@ keywords: - workflow start - workflow terminate - workflow trace + - workflow update-options tags: - - Temporal CLI - - Workflows + - call-stack + - cancellation + - child-workflows + - cli-reference + - command-line-interface-cli + - event-history + - query + - resets-feature + - signals + - signals-feature + - stack-trace + - temporal-cli + - termination + - workflow + - workflow-cancel + - workflow-count + - workflow-delete + - workflow-describe + - workflow-execute + - workflow-execution + - workflow-list + - workflow-metadata + - workflow-query + - workflow-reset + - workflow-reset-batch + - workflow-show + - workflow-signal + - workflow-stack + - workflow-start + - workflow-terminate + - workflow-trace + - workflow-update-options --- -[Workflow](/workflows) commands allow operations to be performed on [Workflow Executions](/workflow-execution). +## cancel -Workflow commands use this syntax: -`temporal workflow COMMAND [ARGS]`. +Canceling a running Workflow Execution records a +`WorkflowExecutionCancelRequested` event in the Event History. The Service +schedules a new Command Task, and the Workflow Execution performs any cleanup +work supported by its implementation. -## cancel +Use the Workflow ID to cancel an Execution: -The `temporal workflow cancel` command cancels a [Workflow Execution](/workflow-execution). +``` +temporal workflow cancel \ + --workflow-id YourWorkflowId +``` -Canceling a running Workflow Execution records a [`WorkflowExecutionCancelRequested` event](/references/events#workflowexecutioncancelrequested) in the [Event History](/workflow-execution/event#event-history). -A new [Workflow Task](/tasks#workflow-task) will be scheduled, and the Workflow Execution performs cleanup work. +A visibility Query lets you send bulk cancellations to Workflow Executions +matching the results: -`temporal workflow cancel --workflow-id=meaningful-business-id` +``` +temporal workflow cancel \ + --query YourQuery +``` -In addition to Workflow IDs, Workflows can also be cancelled by a [List Filter](/list-filter). -`temporal workflow cancel --query=MyListFilter` +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. Use the following options to change the behavior of this command. -- [--fields](/cli/cmd-options#fields) +**Flags:** + +**--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. + +**--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[]_ -- [--address](/cli/cmd-options#address) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--color** _string-enum_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--color](/cli/cmd-options#color) +**--command-timeout** _duration_ -- [--command-timeout](/cli/cmd-options#command-timeout) +The command execution timeout. 0s means no timeout. -- [--env](/cli/cmd-options#env) +**--env** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Active environment name (`ENV`). (default "default") -- [--namespace](/cli/cmd-options#namespace) +**--env-file** _string_ -- [--query](/cli/cmd-options#query) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--reason](/cli/cmd-options#reason) +**--grpc-meta** _string[]_ -- [--run-id](/cli/cmd-options#run-id) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls](/cli/cmd-options#tls) +**--log-format** _string-enum_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Log format. Accepted values: text, json. (default "text") -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--log-level** _string-enum_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--namespace**, **-n** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Temporal Service Namespace. (default "default") -- [--workflow-id](/cli/cmd-options#workflow-id) +**--no-json-shorthand-payloads** _bool_ -- [--yes](/cli/cmd-options#yes) +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") + +**--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. + +**--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. ## count -The `temporal workflow count` command returns a count of [Workflow Executions](/workflow-execution). -This command requires Elasticsearch to be enabled. +Show a count of Workflow Executions, regardless of execution state (running, +terminated, etc). Use `--query` to select a subset of Workflow Executions: + +``` +temporal workflow count \ + --query YourQuery +``` + +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--query**, **-q** _string_ + +Content for an SQL-like `QUERY` List Filter. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -Use the following options to change the command's behavior. +**--api-key** _string_ -- [--address](/cli/cmd-options#address) +API key for request. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--codec-auth** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Authorization header for Codec Server requests. -- [--color](/cli/cmd-options#color) +**--codec-endpoint** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Remote Codec Server endpoint. -- [--env](/cli/cmd-options#env) +**--codec-header** _string[]_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--namespace](/cli/cmd-options#namespace) +**--color** _string-enum_ -- [--query](/cli/cmd-options#query) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--tls](/cli/cmd-options#tls) +**--command-timeout** _duration_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +The command execution timeout. 0s means no timeout. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--env** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Active environment name (`ENV`). (default "default") -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--env-file** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +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. + +**--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") + +**--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. + +**--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. ## delete -The `temporal workflow delete` command deletes the specified [Workflow Execution](/workflow-execution). +Delete a Workflow Executions and its Event History: + +``` +temporal workflow delete \ + --workflow-id YourWorkflowId +``` + +The removal executes asynchronously. If the Execution is Running, the Service +terminates it before deletion. + +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--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. + +**--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_ -Use the following options to change the command's behavior. +The command execution timeout. 0s means no timeout. -- [--address](/cli/cmd-options#address) +**--env** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Active environment name (`ENV`). (default "default") -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--env-file** _string_ -- [--color](/cli/cmd-options#color) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--grpc-meta** _string[]_ -- [--env](/cli/cmd-options#env) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--log-format** _string-enum_ -- [--namespace](/cli/cmd-options#namespace) +Log format. Accepted values: text, json. (default "text") -- [--query](/cli/cmd-options#query) +**--log-level** _string-enum_ -- [--reason](/cli/cmd-options#reason) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--run-id](/cli/cmd-options#run-id) +**--namespace**, **-n** _string_ -- [--tls](/cli/cmd-options#tls) +Temporal Service Namespace. (default "default") -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--no-json-shorthand-payloads** _bool_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Raw payload output, even if the JSON option was used. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--output**, **-o** _string-enum_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--time-format** _string-enum_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--yes](/cli/cmd-options#yes) +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--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. ## describe -The `temporal workflow describe` command shows information about a given [Workflow Execution](/workflow-execution). -This information can be used to locate Workflow Executions that weren't able to run successfully. +Display information about a specific Workflow Execution: + +``` +temporal workflow describe \ + --workflow-id YourWorkflowId +``` + +Show the Workflow Execution's auto-reset points: + +``` +temporal workflow describe \ + --workflow-id YourWorkflowId \ + --reset-points true +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--raw** _bool_ + +Print properties without changing their format. + +**--reset-points** _bool_ + +Show auto-reset points only. + +**--run-id**, **-r** _string_ + +Run ID. + +**--workflow-id**, **-w** _string_ + +Workflow ID. Required. + +**Global Flags:** -`temporal workflow describe --workflow-id=meaningful-business-id` +**--address** _string_ -The output of this command can be changed to show as printed ('raw') or to only show the Workflow Execution's auto-reset points. +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -`temporal workflow describe --workflow-id=meaningful-business-id --raw=true --reset-points=true` +**--api-key** _string_ -Use the following command options to change the information returned by this command. +API key for request. -- [--address](/cli/cmd-options#address) +**--codec-auth** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Authorization header for Codec Server requests. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--codec-endpoint** _string_ -- [--color](/cli/cmd-options#color) +Remote Codec Server endpoint. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--codec-header** _string[]_ -- [--env](/cli/cmd-options#env) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--color** _string-enum_ -- [--namespace](/cli/cmd-options#namespace) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--raw](/cli/cmd-options#raw) +**--command-timeout** _duration_ -- [--reset-points](/cli/cmd-options#reset-points) +The command execution timeout. 0s means no timeout. -- [--run-id](/cli/cmd-options#run-id) +**--env** _string_ -- [--tls](/cli/cmd-options#tls) +Active environment name (`ENV`). (default "default") -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--env-file** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--grpc-meta** _string[]_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--log-format** _string-enum_ -- [--workflow-id](/cli/cmd-options#workflow-id) +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") + +**--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. + +**--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. ## execute -The `temporal workflow execute` command starts a new [Workflow Execution](/workflow-execution) and prints its progress. -The command doesn't finish until the Workflow Execution completes. +Establish a new Workflow Execution and direct its progress to stdout. The +command blocks and returns when the Workflow Execution completes. If your +Workflow requires input, pass valid JSON: -To execute a [Workflow](/workflows) from the Temporal CLI: -`temporal workflow execute --workflow-id=meaningful-business-id --type=MyWorkflow --task-queue=MyTaskQueue` +``` +temporal workflow execute + --workflow-id YourWorkflowId \ + --type YourWorkflow \ + --task-queue YourTaskQueue \ + --input '{"some-key": "some-value"}' +``` -Single quotes('') are used to wrap input as JSON. +Use `--event-details` to relay updates to the command-line output in JSON +format. When using JSON output (`--output json`), this includes the entire +"history" JSON key for the run. -`temporal workflow execute --workflow-id=meaningful-business-id --type-MyWorkflow --task-queue-MyTaskQueue --input='{"JSON": "Input"}'` +Use the following options to change the behavior of this command. -Use the following command options to change how the Workflow Execution behaves during its run. +**Flags:** -- [--address](/cli/cmd-options#address) +**--cron** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Cron schedule for the Workflow. Deprecated. Use Schedules instead. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--detailed** _bool_ -- [--color](/cli/cmd-options#color) +Display events as sections instead of table. Does not apply to JSON output. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--execution-timeout** _duration_ -- [--cron](/cli/cmd-options#cron) +Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks. -- [--env](/cli/cmd-options#env) +**--fail-existing** _bool_ -- [--execution-timeout](/cli/cmd-options#execution-timeout) +Fail if the Workflow already exists. -- [--fields](/cli/cmd-options#fields) +**--id-conflict-policy** _string-enum_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Determines how to resolve a conflict when spawning a new Workflow Execution with a particular Workflow Id used by an existing Open Workflow Execution. Accepted values: Fail, UseExisting, TerminateExisting. -- [--id-reuse-policy](/cli/cmd-options#id-reuse-policy) +**--id-reuse-policy** _string-enum_ -- [--input](/cli/cmd-options#input) +Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning. -- [--input-file](/cli/cmd-options#input-file) +**--input**, **-i** _string[]_ -- [--limit](/cli/cmd-options#limit) +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. -- [--max-field-length](/cli/cmd-options#max-field-length) +**--input-base64** _bool_ -- [--memo](/cli/cmd-options#memo) +Assume inputs are base64-encoded and attempt to decode them. -- [--memo-file](/cli/cmd-options#memo-file) +**--input-file** _string[]_ -- [--namespace](/cli/cmd-options#namespace) +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. -- [--no-pager](/cli/cmd-options#no-pager) +**--input-meta** _string[]_ -- [--output](/cli/cmd-options#output) +Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. -- [--pager](/cli/cmd-options#pager) +**--memo** _string[]_ -- [--run-timeout](/cli/cmd-options#run-timeout) +Memo using 'KEY="VALUE"' pairs. Use JSON values. -- [--search-attribute](/cli/cmd-options#search-attribute) +**--run-timeout** _duration_ -- [--start-delay](/cli/cmd-options#start-delay) +Fail a Workflow Run if it lasts longer than `DURATION`. -- [--task-queue](/cli/cmd-options#task-queue) +**--search-attribute** _string[]_ -- [--task-timeout](/cli/cmd-options#task-timeout) +Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. -- [--time-format](/cli/cmd-options#time-format) +**--start-delay** _duration_ -- [--tls](/cli/cmd-options#tls) +Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--static-details** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +:::note -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Option is experimental. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +::: -- [--type](/cli/cmd-options#type) +**--static-summary** _string_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line. -## list +:::note -The `temporal workflow list` command provides a list of [Workflow Executions](/workflow-execution) that meet the criteria of a given [List Filter](/list-filter). -By default, this command returns a list of up to 10 closed Workflow Executions. +Option is experimental. -`temporal workflow list --query=MyListFilter` +::: -The command can also return a list of archived Workflow Executions. +**--task-queue**, **-t** _string_ -`temporal workflow list --archived=true` +Workflow Task queue. Required. -Use the following command options to change the information returned by this command. +**--task-timeout** _duration_ -- [--address](/cli/cmd-options#address) +Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s") -- [--archived](/cli/cmd-options#archived) +**--type** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Workflow Type name. Required. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--workflow-id**, **-w** _string_ -- [--color](/cli/cmd-options#color) +Workflow ID. If not supplied, the Service generates a unique ID. -- [--command-timeout](/cli/cmd-options#command-timeout) +**Global Flags:** -- [--env](/cli/cmd-options#env) +**--address** _string_ -- [--fields](/cli/cmd-options#fields) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--api-key** _string_ -- [--limit](/cli/cmd-options#limit) +API key for request. -- [--namespace](/cli/cmd-options#namespace) +**--codec-auth** _string_ -- [--no-pager](/cli/cmd-options#no-pager) +Authorization header for Codec Server requests. -- [--output](/cli/cmd-options#output) +**--codec-endpoint** _string_ -- [--pager](/cli/cmd-options#pager) +Remote Codec Server endpoint. -- [--query](/cli/cmd-options#query) +**--codec-header** _string[]_ -- [--time-format](/cli/cmd-options#time-format) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls](/cli/cmd-options#tls) +**--color** _string-enum_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--command-timeout** _duration_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +The command execution timeout. 0s means no timeout. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--env** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Active environment name (`ENV`). (default "default") -## query +**--env-file** _string_ -The `temporal workflow query` command sends a [Query](/sending-messages#sending-queries) to a [Workflow Execution](/workflow-execution). +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -Queries can retrieve all or part of the Workflow state within given parameters. -Queries can also be used on completed [Workflows](/workflow-execution). +**--grpc-meta** _string[]_ -`temporal workflow query --workflow-id=meaningful-business-id --type=MyQueryType` +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -Use the following command options to change the information returned by this command. +**--log-format** _string-enum_ -- [--address](/cli/cmd-options#address) +Log format. Accepted values: text, json. (default "text") -- [--codec-auth](/cli/cmd-options#codec-auth) +**--log-level** _string-enum_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--color](/cli/cmd-options#color) +**--namespace**, **-n** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Temporal Service Namespace. (default "default") -- [--env](/cli/cmd-options#env) +**--no-json-shorthand-payloads** _bool_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Raw payload output, even if the JSON option was used. -- [--input](/cli/cmd-options#input) +**--output**, **-o** _string-enum_ -- [--input-file](/cli/cmd-options#input-file) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--namespace](/cli/cmd-options#namespace) +**--time-format** _string-enum_ -- [--reject-condition](/cli/cmd-options#reject-condition) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--run-id](/cli/cmd-options#run-id) +**--tls** _bool_ -- [--tls](/cli/cmd-options#tls) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--tls-ca-data** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls-ca-path** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--tls-cert-data** _string_ -- [--type](/cli/cmd-options#type) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--workflow-id](/cli/cmd-options#workflow-id) +**--tls-cert-path** _string_ -## reset +Path to x509 certificate. Can't be used with --tls-cert-data. -The `temporal workflow reset` command resets a [Workflow Execution](/workflow-execution). -A reset resumes the Workflow from a certain point without losing your parameters or [Event History](/workflow-execution/event#event-history). +**--tls-disable-host-verification** _bool_ -The Workflow Execution can be set to a given [Event Type](/workflow-execution/event#event). -For example, `temporal workflow reset --workflow-id=meaningful-business-id --type=LastContinuedAsNew`. +Disable TLS host-name verification. -The Workflow Execution can also be reset to any Event after WorkflowTaskStarted. -For example, `temporal workflow reset --workflow-id=meaningful-business-id --event-id=MyLastEvent`. +**--tls-key-data** _string_ -Use the following options to change reset behavior. +Private certificate key data. Can't be used with --tls-key-path. -- [--address](/cli/cmd-options#address) +**--tls-key-path** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Path to x509 private key. Can't be used with --tls-key-data. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--tls-server-name** _string_ -- [--color](/cli/cmd-options#color) +Override target TLS server name. -- [--command-timeout](/cli/cmd-options#command-timeout) +## fix-history-json -- [--env](/cli/cmd-options#env) +Reserialize an Event History JSON file: -- [--event-id](/cli/cmd-options#event-id) +``` +temporal workflow fix-history-json \ + --source /path/to/original.json \ + --target /path/to/reserialized.json +``` -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Use the following options to change the behavior of this command. -- [--namespace](/cli/cmd-options#namespace) +**Flags:** -- [--reapply-type](/cli/cmd-options#reapply-type) +**--source**, **-s** _string_ -- [--reason](/cli/cmd-options#reason) +Path to the original file. Required. -- [--run-id](/cli/cmd-options#run-id) +**--target**, **-t** _string_ -- [--tls](/cli/cmd-options#tls) +Path to the results file. When omitted, output is sent to stdout. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**Global Flags:** -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--address** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--api-key** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +API key for request. -- [--type](/cli/cmd-options#type) +**--codec-auth** _string_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Authorization header for Codec Server requests. -## reset-batch +**--codec-endpoint** _string_ -The `temporal workflow reset-batch` command resets multiple [Workflow Executions](/workflow-execution) by `resetType`. -Resetting a [Workflow](/workflows) resumes it from a certain point without losing your parameters or [Event History](/workflow-execution/event#event-history). +Remote Codec Server endpoint. -The set of Workflow Executions to reset can be specified in an input file. -The input file must have a [Workflow ID](/workflow-execution/workflowid-runid#workflow-id) on each line. +**--codec-header** _string[]_ -`temporal workflow reset-batch --input-file=MyInput --input-separator="\t"` +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -Workflow Executions can also be queried by a [List Filter](/list-filter). -`temporal workflow reset-batch --query=MyListFilter` +**--color** _string-enum_ -Use the following options to change reset behavior. +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--address](/cli/cmd-options#address) +**--command-timeout** _duration_ -- [--codec-auth](/cli/cmd-options#codec-auth) +The command execution timeout. 0s means no timeout. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--env** _string_ -- [--color](/cli/cmd-options#color) +Active environment name (`ENV`). (default "default") -- [--command-timeout](/cli/cmd-options#command-timeout) +**--env-file** _string_ -- [--dry-run](/cli/cmd-options#dry-run) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--env](/cli/cmd-options#env) +**--grpc-meta** _string[]_ -- [--exclude-file](/cli/cmd-options#exclude-file) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--log-format** _string-enum_ -- [--input-file](/cli/cmd-options#input-file) +Log format. Accepted values: text, json. (default "text") -- [--input-parallelism](/cli/cmd-options#input-parallelism) +**--log-level** _string-enum_ -- [--input-separator](/cli/cmd-options#input-separator) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--namespace](/cli/cmd-options#namespace) +**--namespace**, **-n** _string_ -- [--non-deterministic](/cli/cmd-options#non-deterministic) +Temporal Service Namespace. (default "default") -- [--query](/cli/cmd-options#query) +**--no-json-shorthand-payloads** _bool_ -- [--reason](/cli/cmd-options#reason) +Raw payload output, even if the JSON option was used. -- [--skip-base-is-not-current](/cli/cmd-options#skip-base-is-not-current) +**--output**, **-o** _string-enum_ -- [--skip-current-open](/cli/cmd-options#skip-current-open) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--tls](/cli/cmd-options#tls) +**--time-format** _string-enum_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--tls** _bool_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--tls-ca-data** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--type](/cli/cmd-options#type) +**--tls-ca-path** _string_ -## show +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. + +## list -The `temporal workflow show` command provides the [Event History](/workflow-execution/event#event-history) for a [Workflow Execution](/workflow-execution). +List Workflow Executions. The optional `--query` limits the output to +Workflows matching a Query: + +``` +temporal workflow list \ + --query YourQuery` +``` + +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. + +View a list of archived Workflow Executions: + +``` +temporal workflow list \ + --archived +``` Use the following options to change the behavior of this command. -- [--address](/cli/cmd-options#address) +**Flags:** -- [--codec-auth](/cli/cmd-options#codec-auth) +**--archived** _bool_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Limit output to archived Workflow Executions. -- [--color](/cli/cmd-options#color) +:::note -- [--command-timeout](/cli/cmd-options#command-timeout) +Option is experimental. -- [--env](/cli/cmd-options#env) +::: -- [--fields](/cli/cmd-options#fields) +**--limit** _int_ -- [--follow](/cli/cmd-options#follow) +Maximum number of Workflow Executions to display. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--page-size** _int_ -- [--limit](/cli/cmd-options#limit) +Maximum number of Workflow Executions to fetch at a time from the server. -- [--max-field-length](/cli/cmd-options#max-field-length) +**--query**, **-q** _string_ -- [--namespace](/cli/cmd-options#namespace) +Content for an SQL-like `QUERY` List Filter. -- [--no-pager](/cli/cmd-options#no-pager) +**Global Flags:** -- [--output](/cli/cmd-options#output) +**--address** _string_ -- [--pager](/cli/cmd-options#pager) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--reset-points](/cli/cmd-options#reset-points) +**--api-key** _string_ -- [--run-id](/cli/cmd-options#run-id) +API key for request. -- [--time-format](/cli/cmd-options#time-format) +**--codec-auth** _string_ -- [--tls](/cli/cmd-options#tls) +Authorization header for Codec Server requests. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--codec-endpoint** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Remote Codec Server endpoint. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--codec-header** _string[]_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--color** _string-enum_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Output coloring. Accepted values: always, never, auto. (default "auto") -## signal +**--command-timeout** _duration_ -The `temporal workflow signal` command is used to send a [Signal](/sending-messages#sending-signals) to a [Workflow Execution](/workflow-execution) by [Workflow Id](/workflow-execution/workflowid-runid#workflow-id) or [List Filter](/list-filter). +The command execution timeout. 0s means no timeout. -Use the following options to change the command's behavior. +**--env** _string_ -- [--address](/cli/cmd-options#address) +Active environment name (`ENV`). (default "default") -- [--codec-auth](/cli/cmd-options#codec-auth) +**--env-file** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--color](/cli/cmd-options#color) +**--grpc-meta** _string[]_ -- [--command-timeout](/cli/cmd-options#command-timeout) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--env](/cli/cmd-options#env) +**--log-format** _string-enum_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Log format. Accepted values: text, json. (default "text") -- [--input](/cli/cmd-options#input) +**--log-level** _string-enum_ -- [--input-file](/cli/cmd-options#input-file) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--name](/cli/cmd-options#name) +**--namespace**, **-n** _string_ -- [--namespace](/cli/cmd-options#namespace) +Temporal Service Namespace. (default "default") -- [--query](/cli/cmd-options#query) +**--no-json-shorthand-payloads** _bool_ -- [--reason](/cli/cmd-options#reason) +Raw payload output, even if the JSON option was used. -- [--run-id](/cli/cmd-options#run-id) +**--output**, **-o** _string-enum_ -- [--tls](/cli/cmd-options#tls) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--time-format** _string-enum_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls** _bool_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--tls-ca-data** _string_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--yes](/cli/cmd-options#yes) +**--tls-ca-path** _string_ -## stack +Path to server CA certificate. Can't be used with --tls-ca-data. -The `temporal workflow stack` command queries a [Workflow Execution](/workflow-execution) with `--stack-trace` as the [Query](/sending-messages#stack-trace-query) type. -Returning the call stack of all the threads owned by a Workflow Execution can be great for troubleshooting in production. +**--tls-cert-data** _string_ -Use the following options to change the command's behavior. +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--address](/cli/cmd-options#address) +**--tls-cert-path** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--tls-disable-host-verification** _bool_ -- [--color](/cli/cmd-options#color) +Disable TLS host-name verification. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--tls-key-data** _string_ -- [--env](/cli/cmd-options#env) +Private certificate key data. Can't be used with --tls-key-path. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--tls-key-path** _string_ -- [--input](/cli/cmd-options#input) +Path to x509 private key. Can't be used with --tls-key-data. -- [--input-file](/cli/cmd-options#input-file) +**--tls-server-name** _string_ -- [--namespace](/cli/cmd-options#namespace) +Override target TLS server name. -- [--reject-condition](/cli/cmd-options#reject-condition) +## metadata -- [--run-id](/cli/cmd-options#run-id) +Issue a Query for and display user-set metadata like summary and +details for a specific Workflow Execution: -- [--tls](/cli/cmd-options#tls) +``` +temporal workflow metadata \ + --workflow-id YourWorkflowId +``` -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Use the following options to change the behavior of this command. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**Flags:** -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--reject-condition** _string-enum_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Optional flag for rejecting Queries based on Workflow state. Accepted values: not_open, not_completed_cleanly. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--run-id**, **-r** _string_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Run ID. -## start +**--workflow-id**, **-w** _string_ -The `temporal workflow start` command starts a new [Workflow Execution](/workflow-execution). -When invoked successfully, the Workflow and Run ID are returned immediately after starting the [Workflow](/workflows). +Workflow ID. Required. -`temporal workflow start --task-queue=MyTaskQueue --type=MyWorkflow` +**Global Flags:** -Use the following command options to change how the Workflow Execution behaves upon starting. +**--address** _string_ -- [--address](/cli/cmd-options#address) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--codec-auth](/cli/cmd-options#codec-auth) +**--api-key** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +API key for request. -- [--color](/cli/cmd-options#color) +**--codec-auth** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Authorization header for Codec Server requests. -- [--cron](/cli/cmd-options#cron) +**--codec-endpoint** _string_ -- [--env](/cli/cmd-options#env) +Remote Codec Server endpoint. -- [--execution-timeout](/cli/cmd-options#execution-timeout) +**--codec-header** _string[]_ -- [--fields](/cli/cmd-options#fields) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--color** _string-enum_ -- [--id-reuse-policy](/cli/cmd-options#id-reuse-policy) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--input](/cli/cmd-options#input) +**--command-timeout** _duration_ -- [--input-file](/cli/cmd-options#input-file) +The command execution timeout. 0s means no timeout. -- [--limit](/cli/cmd-options#limit) +**--env** _string_ -- [--max-field-length](/cli/cmd-options#max-field-length) +Active environment name (`ENV`). (default "default") -- [--memo](/cli/cmd-options#memo) +**--env-file** _string_ -- [--memo-file](/cli/cmd-options#memo-file) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--namespace](/cli/cmd-options#namespace) +**--grpc-meta** _string[]_ -- [--no-pager](/cli/cmd-options#no-pager) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--output](/cli/cmd-options#output) +**--log-format** _string-enum_ -- [--pager](/cli/cmd-options#pager) +Log format. Accepted values: text, json. (default "text") -- [--run-timeout](/cli/cmd-options#run-timeout) +**--log-level** _string-enum_ -- [--search-attribute](/cli/cmd-options#search-attribute) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--start-delay](/cli/cmd-options#start-delay) +**--namespace**, **-n** _string_ -- [--task-queue](/cli/cmd-options#task-queue) +Temporal Service Namespace. (default "default") -- [--task-timeout](/cli/cmd-options#task-timeout) +**--no-json-shorthand-payloads** _bool_ -- [--time-format](/cli/cmd-options#time-format) +Raw payload output, even if the JSON option was used. -- [--tls](/cli/cmd-options#tls) +**--output**, **-o** _string-enum_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--time-format** _string-enum_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--tls** _bool_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--type](/cli/cmd-options#type) +**--tls-ca-data** _string_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Data for server CA certificate. Can't be used with --tls-ca-path. -## terminate +**--tls-ca-path** _string_ -The `temporal workflow terminate` command terminates a [Workflow Execution](/workflow-execution) +Path to server CA certificate. Can't be used with --tls-ca-data. -Terminating a running Workflow Execution records a [`WorkflowExecutionTerminated` event](/references/events#workflowexecutionterminated) as the closing Event in the [Event History](/workflow-execution/event#event-history). -Any further [Command](/workflow-execution#command) Tasks cannot be scheduled after running this command. +**--tls-cert-data** _string_ -Workflow terminations require a valid [Workflow ID](/workflow-execution/workflowid-runid#workflow-id) to function. -`temporal workflow terminate --workflow-id=meaningful-business-id` +Data for x509 certificate. Can't be used with --tls-cert-path. -Use the following options to change termination behavior. +**--tls-cert-path** _string_ -- [--address](/cli/cmd-options#address) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--tls-disable-host-verification** _bool_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Disable TLS host-name verification. -- [--color](/cli/cmd-options#color) +**--tls-key-data** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Private certificate key data. Can't be used with --tls-key-path. -- [--env](/cli/cmd-options#env) +**--tls-key-path** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Path to x509 private key. Can't be used with --tls-key-data. -- [--namespace](/cli/cmd-options#namespace) +**--tls-server-name** _string_ -- [--query](/cli/cmd-options#query) +Override target TLS server name. -- [--reason](/cli/cmd-options#reason) +## query -- [--run-id](/cli/cmd-options#run-id) +Send a Query to a Workflow Execution by Workflow ID to retrieve its state. +This synchronous operation exposes the internal state of a running Workflow +Execution, which constantly changes. You can query both running and completed +Workflow Executions: -- [--tls](/cli/cmd-options#tls) +``` +temporal workflow query \ + --workflow-id YourWorkflowId + --type YourQueryType + --input '{"YourInputKey": "YourInputValue"}' +``` -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Use the following options to change the behavior of this command. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**Flags:** -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--input**, **-i** _string[]_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +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. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--input-base64** _bool_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Assume inputs are base64-encoded and attempt to decode them. -- [--yes](/cli/cmd-options#yes) +**--input-file** _string[]_ -## trace +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. -The `temporal workflow trace` command tracks the progress of a [Workflow Execution](/workflow-execution) and any [Child Workflows](/child-workflows) it generates. +**--input-meta** _string[]_ -Use the following options to change the command's behavior. +Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. -- [--address](/cli/cmd-options#address) +**--name** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Query Type/Name. Required. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--reject-condition** _string-enum_ -- [--color](/cli/cmd-options#color) +Optional flag for rejecting Queries based on Workflow state. Accepted values: not_open, not_completed_cleanly. -- [--concurrency](/cli/cmd-options#concurrency) +**--run-id**, **-r** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Run ID. -- [--depth](/cli/cmd-options#depth) +**--workflow-id**, **-w** _string_ -- [--env](/cli/cmd-options#env) +Workflow ID. Required. -- [--fold](/cli/cmd-options#fold) +**Global Flags:** -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--address** _string_ -- [--namespace](/cli/cmd-options#namespace) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--no-fold](/cli/cmd-options#no-fold) +**--api-key** _string_ -- [--run-id](/cli/cmd-options#run-id) +API key for request. -- [--tls](/cli/cmd-options#tls) +**--codec-auth** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Authorization header for Codec Server requests. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--codec-endpoint** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Remote Codec Server endpoint. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--codec-header** _string[]_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--workflow-id](/cli/cmd-options#workflow-id) +**--color** _string-enum_ -## update +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--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. + +**--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") + +**--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. + +**--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 + +Reset a Workflow Execution so it can resume from a point in its Event History +without losing its progress up to that point: + +``` +temporal workflow reset \ + --workflow-id YourWorkflowId \ + --event-id YourLastEvent +``` + +Start from where the Workflow Execution last continued as new: + +``` +temporal workflow reset \ + --workflow-id YourWorkflowId \ + --type LastContinuedAsNew +``` + +For batch resets, limit your resets to FirstWorkflowTask, LastWorkflowTask, or +BuildId. Do not use Workflow IDs, run IDs, or event IDs with this command. + +Visit https://docs.temporal.io/visibility to read more about Search +Attributes and Query creation. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--build-id** _string_ + +A Build ID. Use only with the BuildId `--type`. Resets the first Workflow task processed by this ID. By default, this reset may be in a prior run, earlier than a Continue as New point. + +**--event-id**, **-e** _int_ + +Event ID to reset to. Event must occur after `WorkflowTaskStarted`. `WorkflowTaskCompleted`, `WorkflowTaskFailed`, etc. are valid. + +**--query**, **-q** _string_ + +Content for an SQL-like `QUERY` List Filter. + +**--reapply-exclude** _string-enum[]_ + +Exclude these event types from re-application. Accepted values: All, Signal, Update. + +**--reapply-type** _string-enum_ + +Types of events to re-apply after reset point. Deprecated. Use --reapply-exclude instead. Accepted values: All, Signal, None. (default "All") + +**--reason** _string_ + +Reason for reset. Required. + +**--run-id**, **-r** _string_ + +Run ID. + +**--type**, **-t** _string-enum_ + +The event type for the reset. Accepted values: FirstWorkflowTask, LastWorkflowTask, LastContinuedAsNew, BuildId. + +**--workflow-id**, **-w** _string_ + +Workflow ID. Required for non-batch reset operations. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +## result + +Wait for and print the result of a Workflow Execution: + +``` +temporal workflow result \ + --workflow-id YourWorkflowId +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--run-id**, **-r** _string_ + +Run ID. + +**--workflow-id**, **-w** _string_ + +Workflow ID. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +## show + +Show a Workflow Execution's Event History. +When using JSON output (`--output json`), you may pass the results to an SDK +to perform a replay: + +``` +temporal workflow show \ + --workflow-id YourWorkflowId + --output json +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--detailed** _bool_ + +Display events as detailed sections instead of table. Does not apply to JSON output. + +**--follow**, **-f** _bool_ + +Follow the Workflow Execution progress in real time. Does not apply to JSON output. + +**--run-id**, **-r** _string_ + +Run ID. + +**--workflow-id**, **-w** _string_ + +Workflow ID. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +## signal + +Send an asynchronous notification (Signal) to a running Workflow Execution by +its Workflow ID. The Signal is written to the History. When you include +`--input`, that data is available for the Workflow Execution to consume: + +``` +temporal workflow signal \ + --workflow-id YourWorkflowId \ + --name YourSignal \ + --input '{"YourInputKey": "YourInputValue"}' +``` + +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--input**, **-i** _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** _bool_ + +Assume inputs are base64-encoded and attempt to decode them. + +**--input-file** _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** _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. + +**--name** _string_ + +Signal name. Required. + +**--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. + +**--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. + +**--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. + +**--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") + +**--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. + +**--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. + +## signal-with-start + +Send an asynchronous notification (Signal) to a Workflow Execution. +If the Workflow Execution is not running or is not found, it starts the +workflow then sends the signal. + +``` +temporal workflow signal-with-start \ + --signal-name YourSignal \ + --signal-input '{"some-key": "some-value"}' \ + --workflow-id YourWorkflowId \ + --type YourWorkflowType \ + --task-queue YourTaskQueue \ + --input '{"some-key": "some-value"}' +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--cron** _string_ + +Cron schedule for the Workflow. Deprecated. Use Schedules instead. + +**--execution-timeout** _duration_ + +Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks. + +**--fail-existing** _bool_ + +Fail if the Workflow already exists. + +**--id-conflict-policy** _string-enum_ + +Determines how to resolve a conflict when spawning a new Workflow Execution with a particular Workflow Id used by an existing Open Workflow Execution. Accepted values: Fail, UseExisting, TerminateExisting. + +**--id-reuse-policy** _string-enum_ + +Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning. + +**--input**, **-i** _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** _bool_ + +Assume inputs are base64-encoded and attempt to decode them. + +**--input-file** _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** _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. + +**--memo** _string[]_ + +Memo using 'KEY="VALUE"' pairs. Use JSON values. + +**--run-timeout** _duration_ + +Fail a Workflow Run if it lasts longer than `DURATION`. + +**--search-attribute** _string[]_ + +Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--signal-input** _string[]_ + +Signal input value. Use JSON content or set --signal-input-meta to override. Can't be combined with --signal-input-file. Can be passed multiple times to pass multiple arguments. + +**--signal-input-base64** _bool_ + +Assume signal inputs are base64-encoded and attempt to decode them. + +**--signal-input-file** _string[]_ + +A path or paths for input file(s). Use JSON content or set --signal-input-meta to override. Can't be combined with --signal-input. Can be passed multiple times to pass multiple arguments. + +**--signal-input-meta** _string[]_ + +Input signal payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. + +**--signal-name** _string_ + +Signal name. Required. + +**--start-delay** _duration_ + +Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately. + +**--static-details** _string_ + +Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines. + +:::note + +Option is experimental. + +::: + +**--static-summary** _string_ + +Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line. + +:::note + +Option is experimental. + +::: + +**--task-queue**, **-t** _string_ + +Workflow Task queue. Required. + +**--task-timeout** _duration_ + +Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s") + +**--type** _string_ + +Workflow Type name. Required. + +**--workflow-id**, **-w** _string_ + +Workflow ID. If not supplied, the Service generates a unique ID. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +## stack + +Perform a Query on a Workflow Execution using a `__stack_trace`-type Query. +Display a stack trace of the threads and routines currently in use by the +Workflow for troubleshooting: + +``` +temporal workflow stack \ + --workflow-id YourWorkflowId +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--reject-condition** _string-enum_ + +Optional flag to reject Queries based on Workflow state. Accepted values: not_open, not_completed_cleanly. + +**--run-id**, **-r** _string_ + +Run ID. + +**--workflow-id**, **-w** _string_ + +Workflow ID. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +## start + +Start a new Workflow Execution. Returns the Workflow- and Run-IDs: + +``` +temporal workflow start \ + --workflow-id YourWorkflowId \ + --type YourWorkflow \ + --task-queue YourTaskQueue \ + --input '{"some-key": "some-value"}' +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--cron** _string_ + +Cron schedule for the Workflow. Deprecated. Use Schedules instead. + +**--execution-timeout** _duration_ + +Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks. + +**--fail-existing** _bool_ + +Fail if the Workflow already exists. + +**--id-conflict-policy** _string-enum_ + +Determines how to resolve a conflict when spawning a new Workflow Execution with a particular Workflow Id used by an existing Open Workflow Execution. Accepted values: Fail, UseExisting, TerminateExisting. + +**--id-reuse-policy** _string-enum_ + +Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning. + +**--input**, **-i** _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** _bool_ + +Assume inputs are base64-encoded and attempt to decode them. + +**--input-file** _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** _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. + +**--memo** _string[]_ + +Memo using 'KEY="VALUE"' pairs. Use JSON values. + +**--run-timeout** _duration_ + +Fail a Workflow Run if it lasts longer than `DURATION`. + +**--search-attribute** _string[]_ + +Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--start-delay** _duration_ + +Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately. + +**--static-details** _string_ + +Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines. + +:::note + +Option is experimental. + +::: + +**--static-summary** _string_ + +Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line. + +:::note + +Option is experimental. + +::: + +**--task-queue**, **-t** _string_ + +Workflow Task queue. Required. + +**--task-timeout** _duration_ + +Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s") + +**--type** _string_ + +Workflow Type name. Required. + +**--workflow-id**, **-w** _string_ + +Workflow ID. If not supplied, the Service generates a unique ID. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +## terminate + +Terminate a Workflow Execution: + +``` +temporal workflow terminate \ + --reason YourReasonForTermination \ + --workflow-id YourWorkflowId +``` + +The reason is optional and defaults to the current user's name. The reason +is stored in the Event History as part of the `WorkflowExecutionTerminated` +event. This becomes the closing Event in the Workflow Execution's history. + +Executions may be terminated in bulk via a visibility Query list filter: + +``` +temporal workflow terminate \ + --query YourQuery \ + --reason YourReasonForTermination +``` + +Workflow code cannot see or respond to terminations. To perform clean-up work +in your Workflow code, use `temporal workflow cancel` instead. + +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--query**, **-q** _string_ + +Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query. + +**--reason** _string_ + +Reason for termination. Defaults to message with the current user's name. + +**--rps** _float_ + +Limit batch's requests per second. Only allowed if query is present. + +**--run-id**, **-r** _string_ + +Run ID. Can only be set with --workflow-id. Do not 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 termination. Can only be used with --query. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + +## trace + +Display the progress of a Workflow Execution and its child workflows with a +real-time trace. This view helps you understand how Workflows are proceeding: + +``` +temporal workflow trace \ + --workflow-id YourWorkflowId +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--concurrency** _int_ + +Number of Workflow Histories to fetch at a time. (default "10") + +**--depth** _int_ + +Set depth for your Child Workflow fetches. Pass -1 to fetch child workflows at any depth. (default "-1") + +**--fold** _string[]_ + +Fold away Child Workflows with the specified statuses. Case-insensitive. Ignored if --no-fold supplied. Available values: running, completed, failed, canceled, terminated, timedout, continueasnew. Can be passed multiple times. + +**--no-fold** _bool_ + +Disable folding. Fetch and display Child Workflows within the set depth. + +**--run-id**, **-r** _string_ + +Run ID. + +**--workflow-id**, **-w** _string_ + +Workflow ID. 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. + +**--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. + +**--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") + +**--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. + +**--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 + +An Update is a synchronous call to a Workflow Execution that can change its +state, control its flow, and return a result. + +Experimental. + +### describe + +Given a Workflow Execution and an Update ID, return information about its current status, including +a result if it has finished. + +Experimental. + +``` +temporal workflow update describe \ + --workflow-id YourWorkflowId \ + --update-id YourUpdateId +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--run-id**, **-r** _string_ + +Run ID. If unset, updates the currently-running Workflow Execution. + +**--update-id** _string_ + +Update ID. Must be unique per Workflow Execution. Required. + +**--workflow-id**, **-w** _string_ + +Workflow ID. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +### execute + +Send a message to a Workflow Execution to invoke an Update handler, and wait for +the update to complete or fail. You can also use this to wait for an existing +update to complete, by submitting an existing update ID. + +Experimental. + +``` +temporal workflow update execute \ + --workflow-id YourWorkflowId \ + --name YourUpdate \ + --input '{"some-key": "some-value"}' +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--first-execution-run-id** _string_ + +Parent Run ID. The update is sent to the last Workflow Execution in the chain started with this Run ID. + +**--input**, **-i** _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** _bool_ + +Assume inputs are base64-encoded and attempt to decode them. + +**--input-file** _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** _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. + +**--name** _string_ + +Handler method name. Required. + +**--run-id**, **-r** _string_ + +Run ID. If unset, looks for an Update against the currently-running Workflow Execution. + +**--update-id** _string_ + +Update ID. If unset, defaults to a UUID. + +**--workflow-id**, **-w** _string_ + +Workflow ID. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +### result + +Given a Workflow Execution and an Update ID, wait for the Update to complete or fail and +print the result. + +Experimental. + +``` +temporal workflow update result \ + --workflow-id YourWorkflowId \ + --update-id YourUpdateId +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--run-id**, **-r** _string_ + +Run ID. If unset, updates the currently-running Workflow Execution. + +**--update-id** _string_ + +Update ID. Must be unique per Workflow Execution. Required. + +**--workflow-id**, **-w** _string_ + +Workflow ID. 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. + +**--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. + +**--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") + +**--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. + +**--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. + +### start + +Send a message to a Workflow Execution to invoke an Update handler, and wait for +the update to be accepted or rejected. You can subsequently wait for the update +to complete by using `temporal workflow update execute`. + +Experimental. + +``` +temporal workflow update start \ + --workflow-id YourWorkflowId \ + --name YourUpdate \ + --input '{"some-key": "some-value"}' +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--first-execution-run-id** _string_ + +Parent Run ID. The update is sent to the last Workflow Execution in the chain started with this Run ID. + +**--input**, **-i** _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** _bool_ + +Assume inputs are base64-encoded and attempt to decode them. + +**--input-file** _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** _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. + +**--name** _string_ + +Handler method name. Required. + +**--run-id**, **-r** _string_ + +Run ID. If unset, looks for an Update against the currently-running Workflow Execution. + +**--update-id** _string_ + +Update ID. If unset, defaults to a UUID. + +**--wait-for-stage** _string-enum_ + +Update stage to wait for. The only option is `accepted`, but this option is required. This is to allow a future version of the CLI to choose a default value. Required. Accepted values: accepted. + +**--workflow-id**, **-w** _string_ + +Workflow ID. 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. + +**--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. + +**--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") + +**--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. + +**--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 + ++---------------------------------------------------------------------+ +| CAUTION: Worflow update-options is experimental. Workflow Execution | +| properties are subject to change. | ++---------------------------------------------------------------------+ + +Modify properties of Workflow Executions: + +``` +temporal workflow update-options [options] +``` + +It can override the Worker Deployment configuration of a +Workflow Execution, which controls Worker Versioning. + +For example, to force Workers in the current Deployment execute the +next Workflow Task change behavior to `auto_upgrade`: + +``` +temporal workflow update-options \ + --workflow-id YourWorkflowId \ + --versioning-override-behavior auto_upgrade +``` + +or to pin the workflow execution to a Worker Deployment, set behavior +to `pinned`: + +``` +temporal workflow update-options \ + --workflow-id YourWorkflowId \ + --versioning-override-behavior pinned \ + --versioning-override-pinned-version \ + YourDeploymentSeriesName.YourDeploymentBuildId +``` + +To remove any previous overrides, set the behavior to +`unspecified`: + +``` +temporal workflow update-options \ + --workflow-id YourWorkflowId \ + --versioning-override-behavior unspecified +``` + +To see the current override use `temporal workflow describe` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--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. + +**--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. + +**--versioning-override-behavior** _string-enum_ + +Override the versioning behavior of a Workflow. Required. Accepted values: unspecified, pinned, auto_upgrade. + +**--versioning-override-pinned-version** _string_ + +Override Pinned Version for a Worker Deployment (Only for pinned). + +**--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. + +**--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. + +**--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") -The `temporal workflow update` command synchronously updates a running [Workflow Execution](/workflow-execution). +**--time-format** _string-enum_ -Use the options listed below to change the command's behavior. +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--address](/cli/cmd-options#address) +**--tls** _bool_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--tls-ca-data** _string_ -- [--color](/cli/cmd-options#color) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--tls-ca-path** _string_ -- [--env](/cli/cmd-options#env) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--first-execution-run-id](/cli/cmd-options#first-execution-run-id) +**--tls-cert-data** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--input](/cli/cmd-options#input) +**--tls-cert-path** _string_ -- [--name](/cli/cmd-options#name) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--namespace](/cli/cmd-options#namespace) +**--tls-disable-host-verification** _bool_ -- [--run-id](/cli/cmd-options#run-id) +Disable TLS host-name verification. -- [--tls](/cli/cmd-options#tls) +**--tls-key-data** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--tls-key-path** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--tls-server-name** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Override target TLS server name. -- [--workflow-id](/cli/cmd-options#workflow-id) From eebc76df45a67a7cda2e16a64800d1e28444d49d Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Fri, 11 Apr 2025 15:16:50 -0700 Subject: [PATCH 02/14] Create new update-cli-docs GH action that CLI repo can trigger --- .github/workflows/update-cli-docs.yml | 87 +++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 .github/workflows/update-cli-docs.yml diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml new file mode 100644 index 0000000000..188da7975c --- /dev/null +++ b/.github/workflows/update-cli-docs.yml @@ -0,0 +1,87 @@ +name: 'Update CLI docs with latest release from CLI repo' + +on: + workflow_dispatch: + inputs: + cli_branch: + description: 'Branch or tag from the CLI repo' + required: true + commit_author: + description: 'Name to use for the commit author' + required: true + commit_author_email: + description: 'Email to use for the commit author' + required: true + commit_message: + description: 'Commit message for the docs update' + required: true + +jobs: + update: + name: 'Pull changes from the CLI repo and update CLI docs' + runs-on: ubuntu-latest + defaults: + run: + shell: bash + + steps: + - name: Generate token + id: generate_token + uses: actions/create-github-app-token@v1 + with: + app-id: ${{ secrets.TEMPORAL_CICD_APP_ID }} + private-key: ${{ secrets.TEMPORAL_CICD_PRIVATE_KEY }} + + - name: Checkout repository + uses: actions/checkout@v4 + with: + path: cli + ref: ${{ github.event.inputs.cli_branch }} + submodules: recursive + persist-credentials: true + token: ${{ steps.generate_token.outputs.token }} + + - name: Checkout docs repo + uses: actions/checkout@v4 + with: + repository: temporalio/documentation + persist-credentials: true + token: ${{ steps.generate_token.outputs.token }} + path: docs + + - name: Setup Go + uses: actions/setup-go@v4 + with: + go-version: '1.22' + + - name: Generate CLI docs + run: | + cd cli/temporalcli/internal/cmd/gen-docs + go run . + + - name: Publish generated docs to documentation repo + env: + GH_TOKEN: ${{ steps.generate_token.outputs.token }} + run: | + set -ex + + git config user.name "${{ github.event.inputs.commit_author }}" + git config user.email "${{ github.event.inputs.commit_author_email }}" + + BRANCH_NAME="cli-update-docs-${{ github.event.inputs.cli_branch }}" + echo "$BRANCH_NAME" + # Remove the "/merge" suffix if it exists TODO: Is this still needed? + BRANCH_NAME=${BRANCH_NAME%/merge} + + cd docs + git checkout -b $BRANCH_NAME + cp ../cli/temporalcli/docs/*.mdx docs/cli/ + git add . + git commit -m "${{ github.event.inputs.commit_message }}" + git push origin "$BRANCH_NAME" + + gh pr create \ + --body "Autogenerated PR from https://github.com/temporalio/cli" \ + --title "${{ github.event.inputs.commit_message }}" \ + --head "$BRANCH_NAME" \ + --base "main" From 755e4893b0922d75474889f0a1427cc56c5c88e9 Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Fri, 11 Apr 2025 15:28:01 -0700 Subject: [PATCH 03/14] give contents and pull-requests write permissions --- .github/workflows/update-cli-docs.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml index 188da7975c..5cc88531ed 100644 --- a/.github/workflows/update-cli-docs.yml +++ b/.github/workflows/update-cli-docs.yml @@ -20,6 +20,9 @@ jobs: update: name: 'Pull changes from the CLI repo and update CLI docs' runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write defaults: run: shell: bash @@ -60,8 +63,6 @@ jobs: go run . - name: Publish generated docs to documentation repo - env: - GH_TOKEN: ${{ steps.generate_token.outputs.token }} run: | set -ex From dfa4c939142034c7a3cda29e7e9c6f493e151fa6 Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Fri, 11 Apr 2025 17:10:46 -0700 Subject: [PATCH 04/14] Hack to get around this action not being in main --- .github/workflows/update-cli-docs.yml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml index 5cc88531ed..078352ed67 100644 --- a/.github/workflows/update-cli-docs.yml +++ b/.github/workflows/update-cli-docs.yml @@ -1,6 +1,9 @@ name: 'Update CLI docs with latest release from CLI repo' on: + push: + branches: + - "cli-docs-autoupdate" workflow_dispatch: inputs: cli_branch: @@ -35,22 +38,22 @@ jobs: app-id: ${{ secrets.TEMPORAL_CICD_APP_ID }} private-key: ${{ secrets.TEMPORAL_CICD_PRIVATE_KEY }} - - name: Checkout repository + - name: Checkout docs repo uses: actions/checkout@v4 with: - path: cli - ref: ${{ github.event.inputs.cli_branch }} - submodules: recursive persist-credentials: true token: ${{ steps.generate_token.outputs.token }} + path: docs - - name: Checkout docs repo + - name: Checkout cli repo uses: actions/checkout@v4 with: - repository: temporalio/documentation + path: cli + ref: ${{ github.event.inputs.cli_branch }} + submodules: recursive persist-credentials: true token: ${{ steps.generate_token.outputs.token }} - path: docs + repository: temporalio/cli - name: Setup Go uses: actions/setup-go@v4 @@ -70,9 +73,6 @@ jobs: git config user.email "${{ github.event.inputs.commit_author_email }}" BRANCH_NAME="cli-update-docs-${{ github.event.inputs.cli_branch }}" - echo "$BRANCH_NAME" - # Remove the "/merge" suffix if it exists TODO: Is this still needed? - BRANCH_NAME=${BRANCH_NAME%/merge} cd docs git checkout -b $BRANCH_NAME From f470d86cde6ae112ab9d004ec165dbd8d38e73b3 Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Fri, 11 Apr 2025 17:30:49 -0700 Subject: [PATCH 05/14] fix git config --- .github/workflows/update-cli-docs.yml | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml index 078352ed67..3c5770fdd3 100644 --- a/.github/workflows/update-cli-docs.yml +++ b/.github/workflows/update-cli-docs.yml @@ -1,4 +1,4 @@ -name: 'Update CLI docs with latest release from CLI repo' +name: 'CLI Docs Update' on: push: @@ -69,20 +69,18 @@ jobs: run: | set -ex + cd docs git config user.name "${{ github.event.inputs.commit_author }}" git config user.email "${{ github.event.inputs.commit_author_email }}" - BRANCH_NAME="cli-update-docs-${{ github.event.inputs.cli_branch }}" - - cd docs - git checkout -b $BRANCH_NAME + git checkout -b ${{ github.event.inputs.cli_branch }} cp ../cli/temporalcli/docs/*.mdx docs/cli/ git add . git commit -m "${{ github.event.inputs.commit_message }}" - git push origin "$BRANCH_NAME" + git push origin "${{ github.event.inputs.cli_branch }}" gh pr create \ --body "Autogenerated PR from https://github.com/temporalio/cli" \ --title "${{ github.event.inputs.commit_message }}" \ - --head "$BRANCH_NAME" \ + --head "${{ github.event.inputs.cli_branch }}" \ --base "main" From 46274fa53d56cfa342bb789cf08e3fb38a9607ac Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Fri, 11 Apr 2025 17:31:29 -0700 Subject: [PATCH 06/14] only run on workflow_dispatch --- .github/workflows/update-cli-docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml index 3c5770fdd3..fa73e46661 100644 --- a/.github/workflows/update-cli-docs.yml +++ b/.github/workflows/update-cli-docs.yml @@ -23,6 +23,7 @@ jobs: update: name: 'Pull changes from the CLI repo and update CLI docs' runs-on: ubuntu-latest + if: ${{ github.event_name == 'workflow_dispatch' }} permissions: contents: write pull-requests: write From 43536824100fb9b0fbd2b171a33c1d779cad04a1 Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Fri, 11 Apr 2025 17:33:52 -0700 Subject: [PATCH 07/14] token must be specified --- .github/workflows/update-cli-docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml index fa73e46661..c7c14a1612 100644 --- a/.github/workflows/update-cli-docs.yml +++ b/.github/workflows/update-cli-docs.yml @@ -67,6 +67,8 @@ jobs: go run . - name: Publish generated docs to documentation repo + env: + GH_TOKEN: ${{ github.token }} run: | set -ex From 69b6dd3a4c13e312fe84732d6c44d428a02cd05b Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Fri, 11 Apr 2025 17:41:05 -0700 Subject: [PATCH 08/14] Now that everything works, clean up code --- .github/workflows/update-cli-docs.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml index c7c14a1612..ffa957f974 100644 --- a/.github/workflows/update-cli-docs.yml +++ b/.github/workflows/update-cli-docs.yml @@ -1,9 +1,6 @@ name: 'CLI Docs Update' on: - push: - branches: - - "cli-docs-autoupdate" workflow_dispatch: inputs: cli_branch: @@ -23,7 +20,6 @@ jobs: update: name: 'Pull changes from the CLI repo and update CLI docs' runs-on: ubuntu-latest - if: ${{ github.event_name == 'workflow_dispatch' }} permissions: contents: write pull-requests: write @@ -45,6 +41,7 @@ jobs: persist-credentials: true token: ${{ steps.generate_token.outputs.token }} path: docs + ref: main - name: Checkout cli repo uses: actions/checkout@v4 From a5145589c603d5bacd0944c0a5a4b0c0eaedaddd Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Mon, 14 Apr 2025 08:06:59 -0700 Subject: [PATCH 09/14] use cli_release_tag and working-directory --- .github/workflows/update-cli-docs.yml | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml index ffa957f974..b117e23ed4 100644 --- a/.github/workflows/update-cli-docs.yml +++ b/.github/workflows/update-cli-docs.yml @@ -3,8 +3,8 @@ name: 'CLI Docs Update' on: workflow_dispatch: inputs: - cli_branch: - description: 'Branch or tag from the CLI repo' + cli_release_tag: + description: 'Release tag from the CLI repo to update docs from' required: true commit_author: description: 'Name to use for the commit author' @@ -43,11 +43,11 @@ jobs: path: docs ref: main - - name: Checkout cli repo + - name: Checkout CLI repo uses: actions/checkout@v4 with: path: cli - ref: ${{ github.event.inputs.cli_branch }} + ref: ${{ github.event.inputs.cli_release_tag }} submodules: recursive persist-credentials: true token: ${{ steps.generate_token.outputs.token }} @@ -59,28 +59,29 @@ jobs: go-version: '1.22' - name: Generate CLI docs + working-directory: cli/temporalcli/internal/cmd/gen-docs run: | - cd cli/temporalcli/internal/cmd/gen-docs go run . - name: Publish generated docs to documentation repo env: GH_TOKEN: ${{ github.token }} + working-directory: docs run: | set -ex - cd docs git config user.name "${{ github.event.inputs.commit_author }}" git config user.email "${{ github.event.inputs.commit_author_email }}" - git checkout -b ${{ github.event.inputs.cli_branch }} + branch_name="update-cli-docs-${{ github.event.inputs.cli_release_tag }}" + git checkout -b $branch_name cp ../cli/temporalcli/docs/*.mdx docs/cli/ git add . git commit -m "${{ github.event.inputs.commit_message }}" - git push origin "${{ github.event.inputs.cli_branch }}" + git push origin "$branch_name" gh pr create \ --body "Autogenerated PR from https://github.com/temporalio/cli" \ --title "${{ github.event.inputs.commit_message }}" \ - --head "${{ github.event.inputs.cli_branch }}" \ + --head "$branch_name" \ --base "main" From 6d21a5065c36839f0017b4e6c750cb2a75a8d6a2 Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Fri, 18 Apr 2025 10:27:25 -0700 Subject: [PATCH 10/14] Fix title, sidebar, and tags. All generated from CLI main --- docs/cli/activity.mdx | 18 +- docs/cli/batch.mdx | 13 +- docs/cli/env.mdx | 15 +- docs/cli/operator.mdx | 33 +-- docs/cli/schedule.mdx | 20 +- docs/cli/server.mdx | 11 +- docs/cli/task-queue.mdx | 11 +- docs/cli/worker.mdx | 19 +- docs/cli/workflow.mdx | 544 ++++++++++++++++++++++++++++++++++++---- 9 files changed, 533 insertions(+), 151 deletions(-) diff --git a/docs/cli/activity.mdx b/docs/cli/activity.mdx index aa376e76cc..4f1ff9dfc4 100644 --- a/docs/cli/activity.mdx +++ b/docs/cli/activity.mdx @@ -1,7 +1,7 @@ --- id: activity -title: temporal activity -sidebar_label: temporal activity +title: Temporal CLI activity command reference +sidebar_label: activity description: Learn how to use Temporal Activity commands for completing or failing Activity Executions in your Workflow. Optimize your Temporal Workflow management effectively. toc_max_heading_level: 4 keywords: @@ -18,18 +18,8 @@ keywords: - command-line-interface-cli - temporal cli tags: - - activity - - activity-complete - - activity-update-options - - activity-pause - - activity-unpause - - activity-reset - - activity-execution - - activity-fail - - cli-reference - - cli-feature - - command-line-interface-cli - - temporal-cli + - Activities + - Temporal CLI --- ## complete diff --git a/docs/cli/batch.mdx b/docs/cli/batch.mdx index 6d31a13639..331c7b2895 100644 --- a/docs/cli/batch.mdx +++ b/docs/cli/batch.mdx @@ -1,7 +1,7 @@ --- id: batch -title: temporal batch -sidebar_label: temporal batch +title: Temporal CLI batch command reference +sidebar_label: batch description: Use Temporal CLI to manage multiple Workflow Executions with Batch Jobs that can Cancel, Signal, or Terminate Workflows. Filter and monitor Batch Jobs effectively. toc_max_heading_level: 4 keywords: @@ -14,14 +14,7 @@ keywords: - command-line-interface-cli - temporal cli tags: - - batch - - batch-describe - - batch-list - - batch-terminate - - cli-reference - - cli-feature - - command-line-interface-cli - - temporal-cli + - Temporal CLI --- ## describe diff --git a/docs/cli/env.mdx b/docs/cli/env.mdx index 3b7daf1423..7090ab84ae 100644 --- a/docs/cli/env.mdx +++ b/docs/cli/env.mdx @@ -1,7 +1,7 @@ --- id: env -title: temporal env -sidebar_label: temporal env +title: Temporal CLI env command reference +sidebar_label: env description: Temporal CLI 'env' commands allow the configuration, setting, deleting, and listing of environmental properties, making it easy to manage Temporal Server instances. toc_max_heading_level: 4 keywords: @@ -16,16 +16,7 @@ keywords: - environment - temporal cli tags: - - cli-reference - - command-line-interface-cli - - configuration - - env - - env-delete - - env-get - - env-list - - env-set - - environment - - temporal-cli + - Temporal CLI --- ## delete diff --git a/docs/cli/operator.mdx b/docs/cli/operator.mdx index 93c9d6a542..081b0c184f 100644 --- a/docs/cli/operator.mdx +++ b/docs/cli/operator.mdx @@ -1,7 +1,7 @@ --- id: operator -title: temporal operator -sidebar_label: temporal operator +title: Temporal CLI operator command reference +sidebar_label: operator description: Operator commands in Temporal allow actions on Namespaces, Search Attributes, Clusters and Nexus Endpoints using specific subcommands. Execute with "temporal operator [command] [subcommand] [options]". toc_max_heading_level: 4 keywords: @@ -34,34 +34,7 @@ keywords: - temporal cli - update tags: - - cli-reference - - cluster - - cluster-health - - cluster-list - - cluster-remove - - cluster-upsert - - command-line-interface-cli - - describe - - namespace - - namespace-create - - namespace-delete - - namespace-describe - - namespace-list - - nexus - - nexus-endpoint - - nexus-endpoint-create - - nexus-endpoint-delete - - nexus-endpoint-get - - nexus-endpoint-list - - nexus-endpoint-update - - operator - - search-attribute - - search-attribute-create - - search-attribute-list - - search-attribute-remove - - system - - temporal-cli - - update + - Temporal CLI --- ## cluster diff --git a/docs/cli/schedule.mdx b/docs/cli/schedule.mdx index 83c6f340b5..0c7f7b4507 100644 --- a/docs/cli/schedule.mdx +++ b/docs/cli/schedule.mdx @@ -1,7 +1,7 @@ --- id: schedule -title: temporal schedule -sidebar_label: temporal schedule +title: Temporal CLI schedule command reference +sidebar_label: schedule description: Temporal's Schedule commands allow users to create, update, and manage Workflow Executions seamlessly for automation, supporting commands for creation, backfill, deletion, and more. toc_max_heading_level: 4 keywords: @@ -20,20 +20,8 @@ keywords: - temporal cli - updates tags: - - backfill - - cli-reference - - command-line-interface-cli - - schedule - - schedule-backfill - - schedule-create - - schedule-delete - - schedule-describe - - schedule-list - - schedule-toggle - - schedule-trigger - - schedule-update - - temporal-cli - - updates + - Temporal CLI + - Schedules --- ## backfill diff --git a/docs/cli/server.mdx b/docs/cli/server.mdx index 9a2b9e877c..43d674567d 100644 --- a/docs/cli/server.mdx +++ b/docs/cli/server.mdx @@ -1,7 +1,7 @@ --- id: server -title: temporal server -sidebar_label: temporal server +title: Temporal CLI server command reference +sidebar_label: server description: Manage your Temporal Server easily with CLI commands. Start a local server using `temporal server start-dev` and access the Web UI at http://localhost:8233. Customize with multiple options. toc_max_heading_level: 4 keywords: @@ -11,11 +11,8 @@ keywords: - server start-dev - temporal cli tags: - - cli-reference - - command-line-interface-cli - - server - - server-start-dev - - temporal-cli + - Temporal CLI + - Development Server --- ## start-dev diff --git a/docs/cli/task-queue.mdx b/docs/cli/task-queue.mdx index 8a26097c0a..81f6951eb4 100644 --- a/docs/cli/task-queue.mdx +++ b/docs/cli/task-queue.mdx @@ -1,7 +1,7 @@ --- id: task-queue -title: temporal task-queue -sidebar_label: temporal task-queue +title: Temporal CLI task-queue command reference +sidebar_label: task-queue description: Temporal Task Queue commands facilitate operations like describing poller info, displaying partitions, fetching compatible Build IDs, and determining Build ID reachability for effective Workflow and Activity management. toc_max_heading_level: 4 keywords: @@ -12,12 +12,7 @@ keywords: - task queue describe - temporal cli tags: - - cli-reference - - command-line-interface-cli - - list-partitions - - task-queue - - task-queue-describe - - temporal-cli + - Temporal CLI --- ## describe diff --git a/docs/cli/worker.mdx b/docs/cli/worker.mdx index 59777d8a51..bdc9359ebd 100644 --- a/docs/cli/worker.mdx +++ b/docs/cli/worker.mdx @@ -1,15 +1,14 @@ --- id: worker -title: temporal worker -sidebar_label: temporal worker +title: Temporal CLI worker command reference +sidebar_label: worker description: Learn how to read or modify state associated with a Worker, such as Worker Deployments. toc_max_heading_level: 4 keywords: - worker - worker deployment tags: - - worker - - worker-deployment + - Temporal CLI --- ## deployment @@ -201,7 +200,7 @@ are met: Version have pollers. - It is not draining. This requirement can be ignored with the option `--skip-drainage`. - + ``` temporal worker deployment delete-version [options] ``` @@ -763,7 +762,7 @@ specify the Deployment Name. temporal worker deployment set-current-version \ --version __unversioned__ \ --deployment-name YourDeploymentName -``` +``` Use the following options to change the behavior of this command. @@ -932,12 +931,12 @@ temporal worker deployment set-ramping-version \ ``` And to remove that ramping: - + ``` temporal worker deployment set-ramping-version \ --version YourDeploymentName.YourBuildID \ --delete -``` +``` Use the following options to change the behavior of this command. @@ -1091,11 +1090,11 @@ For example: ``` The current metadata is also returned with `describe-version`: - + ``` temporal worker deployment describe-version \ --version YourDeploymentName.YourBuildID \ -``` +``` Use the following options to change the behavior of this command. diff --git a/docs/cli/workflow.mdx b/docs/cli/workflow.mdx index 6eceeb9c76..5014f6c605 100644 --- a/docs/cli/workflow.mdx +++ b/docs/cli/workflow.mdx @@ -1,7 +1,7 @@ --- id: workflow -title: temporal workflow -sidebar_label: temporal workflow +title: Temporal CLI workflow command reference +sidebar_label: workflow description: Temporal Workflow commands enable operations on Workflow Executions, such as cancel, count, delete, describe, execute, list, update-options, query, reset, reset-batch, show, signal, stack, start, terminate, trace, and update, enhancing efficiency and control. toc_max_heading_level: 4 keywords: @@ -38,38 +38,8 @@ keywords: - workflow trace - workflow update-options tags: - - call-stack - - cancellation - - child-workflows - - cli-reference - - command-line-interface-cli - - event-history - - query - - resets-feature - - signals - - signals-feature - - stack-trace - - temporal-cli - - termination - - workflow - - workflow-cancel - - workflow-count - - workflow-delete - - workflow-describe - - workflow-execute - - workflow-execution - - workflow-list - - workflow-metadata - - workflow-query - - workflow-reset - - workflow-reset-batch - - workflow-show - - workflow-signal - - workflow-stack - - workflow-start - - workflow-terminate - - workflow-trace - - workflow-update-options + - Temporal CLI + - Workflows --- ## cancel @@ -850,6 +820,251 @@ Path to x509 private key. Can't be used with --tls-key-data. Override target TLS server name. +## execute-update-with-start + +Send a message to a Workflow Execution to invoke an Update handler, and wait for +the update to complete. If the Workflow Execution is not running, then a new workflow +execution is started and the update is sent. + +Experimental. + +``` +temporal workflow execute-update-with-start \ + --update-name YourUpdate \ + --update-input '{"update-key": "update-value"}' \ + --workflow-id YourWorkflowId \ + --type YourWorkflowType \ + --task-queue YourTaskQueue \ + --id-conflict-policy Fail \ + --input '{"wf-key": "wf-value"}' +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--cron** _string_ + +Cron schedule for the Workflow. Deprecated. Use Schedules instead. + +**--execution-timeout** _duration_ + +Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks. + +**--fail-existing** _bool_ + +Fail if the Workflow already exists. + +**--id-conflict-policy** _string-enum_ + +Determines how to resolve a conflict when spawning a new Workflow Execution with a particular Workflow Id used by an existing Open Workflow Execution. Accepted values: Fail, UseExisting, TerminateExisting. + +**--id-reuse-policy** _string-enum_ + +Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning. + +**--input**, **-i** _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** _bool_ + +Assume inputs are base64-encoded and attempt to decode them. + +**--input-file** _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** _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. + +**--memo** _string[]_ + +Memo using 'KEY="VALUE"' pairs. Use JSON values. + +**--run-id**, **-r** _string_ + +Run ID. If unset, looks for an Update against the currently-running Workflow Execution. + +**--run-timeout** _duration_ + +Fail a Workflow Run if it lasts longer than `DURATION`. + +**--search-attribute** _string[]_ + +Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--start-delay** _duration_ + +Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately. + +**--static-details** _string_ + +Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines. + +:::note + +Option is experimental. + +::: + +**--static-summary** _string_ + +Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line. + +:::note + +Option is experimental. + +::: + +**--task-queue**, **-t** _string_ + +Workflow Task queue. Required. + +**--task-timeout** _duration_ + +Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s") + +**--type** _string_ + +Workflow Type name. Required. + +**--update-first-execution-run-id** _string_ + +Parent Run ID. The update is sent to the last Workflow Execution in the chain started with this Run ID. + +**--update-id** _string_ + +Update ID. If unset, defaults to a UUID. + +**--update-input** _string[]_ + +Update input value. Use JSON content or set --update-input-meta to override. Can't be combined with --update-input-file. Can be passed multiple times to pass multiple arguments. + +**--update-input-base64** _bool_ + +Assume update inputs are base64-encoded and attempt to decode them. + +**--update-input-file** _string[]_ + +A path or paths for input file(s). Use JSON content or set --update-input-meta to override. Can't be combined with --update-input. Can be passed multiple times to pass multiple arguments. + +**--update-input-meta** _string[]_ + +Input update payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. + +**--update-name** _string_ + +Update name. Required. + +**--workflow-id**, **-w** _string_ + +Workflow ID. If not supplied, the Service generates a unique ID. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + ## fix-history-json Reserialize an Event History JSON file: @@ -2561,6 +2776,256 @@ Path to x509 private key. Can't be used with --tls-key-data. Override target TLS server name. +## start-update-with-start + +Send a message to a Workflow Execution to invoke an Update handler, and wait for +the update to be accepted or rejected. If the Workflow Execution is not running, +then a new workflow execution is started and the update is sent. + +Experimental. + +``` +temporal workflow start-update-with-start \ + --update-name YourUpdate \ + --update-input '{"update-key": "update-value"}' \ + --update-wait-for-stage accepted \ + --workflow-id YourWorkflowId \ + --type YourWorkflowType \ + --task-queue YourTaskQueue \ + --id-conflict-policy Fail \ + --input '{"wf-key": "wf-value"}' +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--cron** _string_ + +Cron schedule for the Workflow. Deprecated. Use Schedules instead. + +**--execution-timeout** _duration_ + +Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks. + +**--fail-existing** _bool_ + +Fail if the Workflow already exists. + +**--id-conflict-policy** _string-enum_ + +Determines how to resolve a conflict when spawning a new Workflow Execution with a particular Workflow Id used by an existing Open Workflow Execution. Accepted values: Fail, UseExisting, TerminateExisting. + +**--id-reuse-policy** _string-enum_ + +Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning. + +**--input**, **-i** _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** _bool_ + +Assume inputs are base64-encoded and attempt to decode them. + +**--input-file** _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** _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. + +**--memo** _string[]_ + +Memo using 'KEY="VALUE"' pairs. Use JSON values. + +**--run-id**, **-r** _string_ + +Run ID. If unset, looks for an Update against the currently-running Workflow Execution. + +**--run-timeout** _duration_ + +Fail a Workflow Run if it lasts longer than `DURATION`. + +**--search-attribute** _string[]_ + +Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--start-delay** _duration_ + +Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately. + +**--static-details** _string_ + +Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines. + +:::note + +Option is experimental. + +::: + +**--static-summary** _string_ + +Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line. + +:::note + +Option is experimental. + +::: + +**--task-queue**, **-t** _string_ + +Workflow Task queue. Required. + +**--task-timeout** _duration_ + +Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s") + +**--type** _string_ + +Workflow Type name. Required. + +**--update-first-execution-run-id** _string_ + +Parent Run ID. The update is sent to the last Workflow Execution in the chain started with this Run ID. + +**--update-id** _string_ + +Update ID. If unset, defaults to a UUID. + +**--update-input** _string[]_ + +Update input value. Use JSON content or set --update-input-meta to override. Can't be combined with --update-input-file. Can be passed multiple times to pass multiple arguments. + +**--update-input-base64** _bool_ + +Assume update inputs are base64-encoded and attempt to decode them. + +**--update-input-file** _string[]_ + +A path or paths for input file(s). Use JSON content or set --update-input-meta to override. Can't be combined with --update-input. Can be passed multiple times to pass multiple arguments. + +**--update-input-meta** _string[]_ + +Input update payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. + +**--update-name** _string_ + +Update name. Required. + +**--update-wait-for-stage** _string-enum_ + +Update stage to wait for. The only option is `accepted`, but this option is required. This is to allow a future version of the CLI to choose a default value. Required. Accepted values: accepted. + +**--workflow-id**, **-w** _string_ + +Workflow ID. If not supplied, the Service generates a unique ID. + +**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. + +**--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. + +**--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") + +**--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. + +**--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. + ## terminate Terminate a Workflow Execution: @@ -2864,15 +3329,11 @@ Override target TLS server name. An Update is a synchronous call to a Workflow Execution that can change its state, control its flow, and return a result. -Experimental. - ### describe Given a Workflow Execution and an Update ID, return information about its current status, including a result if it has finished. -Experimental. - ``` temporal workflow update describe \ --workflow-id YourWorkflowId \ @@ -3003,8 +3464,6 @@ Send a message to a Workflow Execution to invoke an Update handler, and wait for the update to complete or fail. You can also use this to wait for an existing update to complete, by submitting an existing update ID. -Experimental. - ``` temporal workflow update execute \ --workflow-id YourWorkflowId \ @@ -3159,8 +3618,6 @@ Override target TLS server name. Given a Workflow Execution and an Update ID, wait for the Update to complete or fail and print the result. -Experimental. - ``` temporal workflow update result \ --workflow-id YourWorkflowId \ @@ -3291,13 +3748,12 @@ Send a message to a Workflow Execution to invoke an Update handler, and wait for the update to be accepted or rejected. You can subsequently wait for the update to complete by using `temporal workflow update execute`. -Experimental. - ``` temporal workflow update start \ --workflow-id YourWorkflowId \ --name YourUpdate \ --input '{"some-key": "some-value"}' + --wait-for-stage accepted ``` Use the following options to change the behavior of this command. From 1f35a514718abb110eaa351273b8dca7db187f43 Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Mon, 28 Apr 2025 14:02:18 -0700 Subject: [PATCH 11/14] Add worker to sidebar, fix code fence --- docs/cli/activity.mdx | 2 -- sidebars.js | 1 + 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/cli/activity.mdx b/docs/cli/activity.mdx index 4f1ff9dfc4..04ab6f3975 100644 --- a/docs/cli/activity.mdx +++ b/docs/cli/activity.mdx @@ -300,8 +300,6 @@ Activities can be specified by their Activity ID or Activity Type. One of those parameters must be provided. If both are provided - Activity Type will be used, and Activity ID will be ignored. -``` - Specify the Activity and Workflow IDs: ``` diff --git a/sidebars.js b/sidebars.js index 6399625b8a..9455906e14 100644 --- a/sidebars.js +++ b/sidebars.js @@ -497,6 +497,7 @@ module.exports = { "cli/schedule", "cli/server", "cli/task-queue", + "cli/worker", "cli/workflow", ], }, From 61f7d5ba43ca750501dcdea039f8f7d84bc51e7e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 28 Apr 2025 21:03:26 +0000 Subject: [PATCH 12/14] CI: Automatic .md and .mdx formatting --- docs/cli/activity.mdx | 33 +++++++++++++-------------- docs/cli/batch.mdx | 1 - docs/cli/env.mdx | 1 - docs/cli/operator.mdx | 3 +-- docs/cli/schedule.mdx | 34 ++++++++++++++-------------- docs/cli/server.mdx | 11 +++++---- docs/cli/task-queue.mdx | 40 ++++++++++++++++----------------- docs/cli/worker.mdx | 49 ++++++++++++++++++++--------------------- docs/cli/workflow.mdx | 9 ++++---- 9 files changed, 85 insertions(+), 96 deletions(-) diff --git a/docs/cli/activity.mdx b/docs/cli/activity.mdx index 04ab6f3975..e396aa52ef 100644 --- a/docs/cli/activity.mdx +++ b/docs/cli/activity.mdx @@ -296,7 +296,7 @@ However, if the Activity is currently running, it will run to completion. 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 can be specified by their Activity ID or Activity Type. +Activities can be specified by their Activity ID or Activity Type. One of those parameters must be provided. If both are provided - Activity Type will be used, and Activity ID will be ignored. @@ -428,20 +428,20 @@ Override target TLS server name. ## reset -Resetting an activity resets both the number of attempts and the activity -timeout. +Resetting an activity resets both the number of attempts and the activity +timeout. -If activity is paused and 'keep_paused' flag is not provided - it will be +If activity is paused and 'keep_paused' flag is not provided - it will be unpaused. -If activity is paused and 'keep_paused' flag is provided - it will stay +If activity is paused and 'keep_paused' flag is provided - it will stay paused. If activity is waiting for the retry, is will be rescheduled immediately. -If the 'reset_heartbeats' flag is set, the activity heartbeat timer and +If the 'reset_heartbeats' flag is set, the activity heartbeat timer and heartbeats will be reset. -Activities can be specified by their Activity ID or Activity Type. +Activities can be specified by their Activity ID or Activity Type. One of those parameters must be provided. If both are provided - Activity -Type will be used, and Activity ID will be ignored. +Type will be used, and Activity ID will be ignored. Specify the Activity Type of ID and Workflow IDs: @@ -585,16 +585,16 @@ 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. +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 +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. +Use `--reset-heartbeat` to reset the Activity's heartbeats. -Activities can be specified by their Activity ID or Activity Type. +Activities can be specified by their Activity ID or Activity Type. One of those parameters must be provided. If both are provided - Activity Type will be used, and Activity ID will be ignored. @@ -606,7 +606,6 @@ temporal activity unpause \ --reason YourReasonForTermination ``` - Specify the Activity ID or Type and Workflow IDs: ``` @@ -639,7 +638,7 @@ The activity will start at random a time within the specified duration. Can only **--match-all** _bool_ -Every paused activity should be unpaused. This flag is ignored if activity-type is provided. Can only be used with --query. +Every paused activity should be unpaused. This flag is ignored if activity-type is provided. Can only be used with --query. **--query**, **-q** _string_ @@ -794,7 +793,6 @@ temporal activity update-options \ --retry-maximum-interval DURATION \ --retry-backoff-coefficient NewBackoffCoefficient \ --retry-maximum-attempts NewMaximumAttempts - ``` Use the following options to change the behavior of this command. @@ -946,4 +944,3 @@ Path to x509 private key. Can't be used with --tls-key-data. **--tls-server-name** _string_ Override target TLS server name. - diff --git a/docs/cli/batch.mdx b/docs/cli/batch.mdx index 331c7b2895..2bc48b9507 100644 --- a/docs/cli/batch.mdx +++ b/docs/cli/batch.mdx @@ -382,4 +382,3 @@ Path to x509 private key. Can't be used with --tls-key-data. **--tls-server-name** _string_ Override target TLS server name. - diff --git a/docs/cli/env.mdx b/docs/cli/env.mdx index 7090ab84ae..65b6719012 100644 --- a/docs/cli/env.mdx +++ b/docs/cli/env.mdx @@ -520,4 +520,3 @@ Path to x509 private key. Can't be used with --tls-key-data. **--tls-server-name** _string_ Override target TLS server name. - diff --git a/docs/cli/operator.mdx b/docs/cli/operator.mdx index 081b0c184f..43825158b2 100644 --- a/docs/cli/operator.mdx +++ b/docs/cli/operator.mdx @@ -792,7 +792,7 @@ Create a new Namespace on the Temporal Service: temporal operator namespace create \ --namespace YourNewNamespaceName \ [options] -```` +``` Create a Namespace with multi-region data replication: @@ -2589,4 +2589,3 @@ Path to x509 private key. Can't be used with --tls-key-data. **--tls-server-name** _string_ Override target TLS server name. - diff --git a/docs/cli/schedule.mdx b/docs/cli/schedule.mdx index 0c7f7b4507..6fbfa1fd0e 100644 --- a/docs/cli/schedule.mdx +++ b/docs/cli/schedule.mdx @@ -47,20 +47,20 @@ temporal schedule backfill \ The policies include: -* **AllowAll**: Allow unlimited concurrent Workflow Executions. This +- **AllowAll**: Allow unlimited concurrent Workflow Executions. This significantly speeds up the backfilling process on systems that support concurrency. You must ensure running Workflow Executions do not interfere with each other. -* **BufferAll**: Buffer all incoming Workflow Executions while waiting for +- **BufferAll**: Buffer all incoming Workflow Executions while waiting for the running Workflow Execution to complete. -* **Skip**: If a previous Workflow Execution is still running, discard new +- **Skip**: If a previous Workflow Execution is still running, discard new Workflow Executions. -* **BufferOne**: Same as 'Skip' but buffer a single Workflow Execution to be +- **BufferOne**: Same as 'Skip' but buffer a single Workflow Execution to be run after the previous Execution completes. Discard other Workflow Executions. -* **CancelOther**: Cancel the running Workflow Execution and replace it with +- **CancelOther**: Cancel the running Workflow Execution and replace it with the incoming new Workflow Execution. -* **TerminateOther**: Terminate the running Workflow Execution and replace +- **TerminateOther**: Terminate the running Workflow Execution and replace it with the incoming new Workflow Execution. Use the following options to change the behavior of this command. @@ -185,21 +185,21 @@ new Workflow Executions at the times you specify. For example: ``` - temporal schedule create \ - --schedule-id "YourScheduleId" \ - --calendar '{"dayOfWeek":"Fri","hour":"3","minute":"30"}' \ - --workflow-id YourBaseWorkflowIdName \ - --task-queue YourTaskQueue \ - --type YourWorkflowType +temporal schedule create \ + --schedule-id "YourScheduleId" \ + --calendar '{"dayOfWeek":"Fri","hour":"3","minute":"30"}' \ + --workflow-id YourBaseWorkflowIdName \ + --task-queue YourTaskQueue \ + --type YourWorkflowType ``` Schedules support any combination of `--calendar`, `--interval`, and `--cron`: -* Shorthand `--interval` strings. +- Shorthand `--interval` strings. For example: 45m (every 45 minutes) or 6h/5h (every 6 hours, at the top of the 5th hour). -* JSON `--calendar`, as in the preceding example. -* Unix-style `--cron` strings and robfig declarations +- JSON `--calendar`, as in the preceding example. +- Unix-style `--cron` strings and robfig declarations (@daily/@weekly/@every X/etc). For example, every Friday at 12:30 PM: `30 12 * * Fri`. @@ -451,8 +451,7 @@ temporal schedule delete \ ``` Removing a Schedule won't affect the Workflow Executions it started that are -still running. To cancel or terminate these Workflow Executions, use `temporal -workflow delete` with the `TemporalScheduledById` Search Attribute instead. +still running. To cancel or terminate these Workflow Executions, use `temporal workflow delete` with the `TemporalScheduledById` Search Attribute instead. Use the following options to change the behavior of this command. @@ -1328,4 +1327,3 @@ Path to x509 private key. Can't be used with --tls-key-data. **--tls-server-name** _string_ Override target TLS server name. - diff --git a/docs/cli/server.mdx b/docs/cli/server.mdx index 43d674567d..a6e52d78f9 100644 --- a/docs/cli/server.mdx +++ b/docs/cli/server.mdx @@ -20,11 +20,11 @@ tags: Run a development Temporal Server on your local system. +------------------------------------------------------------------------+ -| WARNING: The development server is not intended for production use. | -| It skips certain HTTP security checks to make local use simpler. | -| | -| For production use, see: | -| https://docs.temporal.io/production-deployment | +| WARNING: The development server is not intended for production use. | +| It skips certain HTTP security checks to make local use simpler. | +| | +| For production use, see: | +| https://docs.temporal.io/production-deployment | +------------------------------------------------------------------------+ View the Web UI for the default configuration at: http://localhost:8233 @@ -224,4 +224,3 @@ Path to x509 private key. Can't be used with --tls-key-data. **--tls-server-name** _string_ Override target TLS server name. - diff --git a/docs/cli/task-queue.mdx b/docs/cli/task-queue.mdx index 81f6951eb4..de09d6529d 100644 --- a/docs/cli/task-queue.mdx +++ b/docs/cli/task-queue.mdx @@ -37,6 +37,7 @@ temporal task-queue describe \ ``` This command provides the following task queue statistics: + - `ApproximateBacklogCount`: The approximate number of tasks backlogged in this task queue. May count expired tasks but eventually converges to the right value. @@ -48,11 +49,11 @@ This command provides the following task queue statistics: (sync-matched tasks), as well as tasks added to the backlog. (See note below.) - `TasksDispatchRate`: Approximate rate at which tasks are being dispatched from the task queue, measured in tasks per second, averaged over the last 30 - seconds. Includes tasks dispatched immediately without going to the backlog + seconds. Includes tasks dispatched immediately without going to the backlog (sync-matched tasks), as well as tasks added to the backlog. (See note below.) - `BacklogIncreaseRate`: Approximate rate at which the backlog size is increasing (if positive) or decreasing (if negative), measured in tasks per - second, averaged over the last 30 seconds. This is roughly equivalent to: + second, averaged over the last 30 seconds. This is roughly equivalent to: `TasksAddRate` - `TasksDispatchRate`. NOTE: The `TasksAddRate` and `TasksDispatchRate` metrics may differ from the @@ -799,9 +800,9 @@ temporal task-queue update-build-ids add-new-default \ ``` +------------------------------------------------------------------------+ -| NOTICE: This command is limited to Namespaces that support Worker | +| NOTICE: This command is limited to Namespaces that support Worker | | versioning. Worker versioning is experimental. Versioning commands are | -| subject to change. | +| subject to change. | +------------------------------------------------------------------------+ Use the following options to change the behavior of this command. @@ -934,9 +935,9 @@ temporal task-queue update-build-ids promote-id-in-set \ ``` +------------------------------------------------------------------------+ -| NOTICE: This command is limited to Namespaces that support Worker | +| NOTICE: This command is limited to Namespaces that support Worker | | versioning. Worker versioning is experimental. Versioning commands are | -| subject to change. | +| subject to change. | +------------------------------------------------------------------------+ Use the following options to change the behavior of this command. @@ -1070,9 +1071,9 @@ temporal task-queue update-build-ids promote-set \ ``` +------------------------------------------------------------------------+ -| NOTICE: This command is limited to Namespaces that support Worker | +| NOTICE: This command is limited to Namespaces that support Worker | | versioning. Worker versioning is experimental. Versioning commands are | -| subject to change. | +| subject to change. | +------------------------------------------------------------------------+ Use the following options to change the behavior of this command. @@ -1192,7 +1193,7 @@ Override target TLS server name. ## versioning +---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | +| CAUTION: This API has been deprecated by Worker Deployment. | +---------------------------------------------------------------------+ Provides commands to add, list, remove, or replace Worker Build ID assignment @@ -1227,7 +1228,7 @@ temporal task-queue versioning add-redirect-rule \ ``` +---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | +| CAUTION: This API has been deprecated by Worker Deployment. | +---------------------------------------------------------------------+ Use the following options to change the behavior of this command. @@ -1372,7 +1373,7 @@ This prevents committing invalid Build IDs. Use the `--force` option to override this validation. +---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | +| CAUTION: This API has been deprecated by Worker Deployment. | +---------------------------------------------------------------------+ Use the following options to change the behavior of this command. @@ -1509,7 +1510,7 @@ hint filter" or "percentage". Otherwise, the delete operation is rejected. Use the `--force` option to override this validation. +---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | +| CAUTION: This API has been deprecated by Worker Deployment. | +---------------------------------------------------------------------+ Use the following options to change the behavior of this command. @@ -1641,7 +1642,7 @@ temporal task-queue versioning delete-redirect-rule \ ``` +---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | +| CAUTION: This API has been deprecated by Worker Deployment. | +---------------------------------------------------------------------+ Use the following options to change the behavior of this command. @@ -1778,9 +1779,9 @@ Task Queues support the following versioning rules: Build ID. You may add at most one redirect rule for each source Build ID. Redirect rules require that a target Build ID is fully compatible with the source Build ID. -+---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | -+---------------------------------------------------------------------+ + +---------------------------------------------------------------------+ + | CAUTION: This API has been deprecated by Worker Deployment. | + +---------------------------------------------------------------------+ Use the following options to change the behavior of this command. @@ -1901,7 +1902,7 @@ temporal task-queue versioning insert-assignment-rule \ If you do not specify a `--rule-index`, this command inserts at index 0. +---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | +| CAUTION: This API has been deprecated by Worker Deployment. | +---------------------------------------------------------------------+ Use the following options to change the behavior of this command. @@ -2055,7 +2056,7 @@ temporal task-queue versioning replace-assignment-rule \ Percent may vary between 0 and 100 (default). +---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | +| CAUTION: This API has been deprecated by Worker Deployment. | +---------------------------------------------------------------------+ Use the following options to change the behavior of this command. @@ -2197,7 +2198,7 @@ temporal task-queue versioning replace-redirect-rule \ ``` +---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | +| CAUTION: This API has been deprecated by Worker Deployment. | +---------------------------------------------------------------------+ Use the following options to change the behavior of this command. @@ -2317,4 +2318,3 @@ Path to x509 private key. Can't be used with --tls-key-data. **--tls-server-name** _string_ Override target TLS server name. - diff --git a/docs/cli/worker.mdx b/docs/cli/worker.mdx index bdc9359ebd..2264870c0b 100644 --- a/docs/cli/worker.mdx +++ b/docs/cli/worker.mdx @@ -15,7 +15,7 @@ tags: +---------------------------------------------------------------------+ | CAUTION: Worker Deployment is experimental. Deployment commands are | -| subject to change. | +| subject to change. | +---------------------------------------------------------------------+ Deployment commands perform operations on Worker Deployments: @@ -50,7 +50,7 @@ Sets the current Deployment Version for a given Deployment. +---------------------------------------------------------------------+ | CAUTION: Worker Deployment is experimental. Deployment commands are | -| subject to change. | +| subject to change. | +---------------------------------------------------------------------+ Remove a Worker Deployment given its Deployment Name. @@ -66,7 +66,6 @@ For example, setting the user identity that removed the deployment: temporal worker deployment delete \ --name YourDeploymentName \ --identity YourIdentity - ``` Use the following options to change the behavior of this command. @@ -187,7 +186,7 @@ Override target TLS server name. +---------------------------------------------------------------------+ | CAUTION: Worker Deployment is experimental. Deployment commands are | -| subject to change. | +| subject to change. | +---------------------------------------------------------------------+ Remove a Worker Deployment Version given its fully-qualified identifier. @@ -195,11 +194,12 @@ This is rarely needed during normal operation since unused Versions are eventually garbage collected. The client can delete a Version only when all of the following conditions are met: - - It is not the Current or Ramping Version for this Deployment. - - It has no active pollers, i.e., none of the task queues in the + +- It is not the Current or Ramping Version for this Deployment. +- It has no active pollers, i.e., none of the task queues in the Version have pollers. - - It is not draining. This requirement can be ignored with the option -`--skip-drainage`. +- It is not draining. This requirement can be ignored with the option + `--skip-drainage`. ``` temporal worker deployment delete-version [options] @@ -210,7 +210,7 @@ For example, skipping the drainage restriction: ``` temporal worker deployment delete-version \ --version YourDeploymentName.YourBuildID \ - --skip-drainage + --skip-drainage ``` Use the following options to change the behavior of this command. @@ -335,7 +335,7 @@ Override target TLS server name. +---------------------------------------------------------------------+ | CAUTION: Worker Deployment is experimental. Deployment commands are | -| subject to change. | +| subject to change. | +---------------------------------------------------------------------+ Describe properties of a Worker Deployment, such as the versions @@ -468,10 +468,10 @@ Override target TLS server name. +---------------------------------------------------------------------+ | CAUTION: Worker Deployment is experimental. Deployment commands are | -| subject to change. | +| subject to change. | +---------------------------------------------------------------------+ -Describe properties of a Worker Deployment Version, such as the task +Describe properties of a Worker Deployment Version, such as the task queues polled by workers in this Deployment Version, or drainage information required to safely decommission workers, or user-provided metadata, or its creation/modification time. @@ -480,7 +480,7 @@ metadata, or its creation/modification time. temporal worker deployment describe-version [options] ``` -For example, to describe a deployment version in a deployment +For example, to describe a deployment version in a deployment `YourDeploymentName`, with Build ID `YourBuildID`, and in the default namespace: @@ -603,7 +603,7 @@ Override target TLS server name. +---------------------------------------------------------------------+ | CAUTION: Worker Deployment is experimental. Deployment commands are | -| subject to change. | +| subject to change. | +---------------------------------------------------------------------+ List existing Worker Deployments in the client's namespace. @@ -727,7 +727,7 @@ Override target TLS server name. +---------------------------------------------------------------------+ | CAUTION: Worker Deployment is experimental. Deployment commands are | -| subject to change. | +| subject to change. | +---------------------------------------------------------------------+ Set the Current Version for a Deployment. @@ -894,13 +894,13 @@ Override target TLS server name. +---------------------------------------------------------------------+ | CAUTION: Worker Deployment is experimental. Deployment commands are | -| subject to change. | +| subject to change. | +---------------------------------------------------------------------+ Set the Ramping Version and Percentage for a Deployment. The Ramping Version can be set to a fully-qualified Version of the form -`YourDeploymentName.YourBuildID`, or set to "__unversioned__", a special +`YourDeploymentName.YourBuildID`, or set to "**unversioned**", a special value that represents all the unversioned workers. The Ramping Percentage is a float with values in the range [0, 100]. @@ -1076,24 +1076,24 @@ Override target TLS server name. +---------------------------------------------------------------------+ | CAUTION: Worker Deployment is experimental. Deployment commands are | -| subject to change. | +| subject to change. | +---------------------------------------------------------------------+ Update metadata associated with a Worker Deployment Version. For example: ``` - temporal worker deployment update-metadata-version \ - --version YourDeploymentName.YourBuildID \ - --metadata bar=1 \ - --metadata foo=true +temporal worker deployment update-metadata-version \ + --version YourDeploymentName.YourBuildID \ + --metadata bar=1 \ + --metadata foo=true ``` The current metadata is also returned with `describe-version`: ``` - temporal worker deployment describe-version \ - --version YourDeploymentName.YourBuildID \ +temporal worker deployment describe-version \ + --version YourDeploymentName.YourBuildID \ ``` Use the following options to change the behavior of this command. @@ -1213,4 +1213,3 @@ Path to x509 private key. Can't be used with --tls-key-data. **--tls-server-name** _string_ Override target TLS server name. - diff --git a/docs/cli/workflow.mdx b/docs/cli/workflow.mdx index 5014f6c605..17786fd6b1 100644 --- a/docs/cli/workflow.mdx +++ b/docs/cli/workflow.mdx @@ -2214,7 +2214,7 @@ Override target TLS server name. ## signal-with-start Send an asynchronous notification (Signal) to a Workflow Execution. -If the Workflow Execution is not running or is not found, it starts the +If the Workflow Execution is not running or is not found, it starts the workflow then sends the signal. ``` @@ -2779,7 +2779,7 @@ Override target TLS server name. ## start-update-with-start Send a message to a Workflow Execution to invoke an Update handler, and wait for -the update to be accepted or rejected. If the Workflow Execution is not running, +the update to be accepted or rejected. If the Workflow Execution is not running, then a new workflow execution is started and the update is sent. Experimental. @@ -3794,7 +3794,7 @@ Update ID. If unset, defaults to a UUID. **--wait-for-stage** _string-enum_ -Update stage to wait for. The only option is `accepted`, but this option is required. This is to allow a future version of the CLI to choose a default value. Required. Accepted values: accepted. +Update stage to wait for. The only option is `accepted`, but this option is required. This is to allow a future version of the CLI to choose a default value. Required. Accepted values: accepted. **--workflow-id**, **-w** _string_ @@ -3906,7 +3906,7 @@ Override target TLS server name. +---------------------------------------------------------------------+ | CAUTION: Worflow update-options is experimental. Workflow Execution | -| properties are subject to change. | +| properties are subject to change. | +---------------------------------------------------------------------+ Modify properties of Workflow Executions: @@ -4086,4 +4086,3 @@ Path to x509 private key. Can't be used with --tls-key-data. **--tls-server-name** _string_ Override target TLS server name. - From eb320744777dea5e6fb18458b4759fefcd98b84f Mon Sep 17 00:00:00 2001 From: Andrew Yuan Date: Mon, 28 Apr 2025 14:05:37 -0700 Subject: [PATCH 13/14] Add in setup page that Erica provided --- docs/cli/setup-cli.mdx | 144 +++++++++++++++++++++++++++++++++++++++++ sidebars.js | 1 + 2 files changed, 145 insertions(+) create mode 100644 docs/cli/setup-cli.mdx diff --git a/docs/cli/setup-cli.mdx b/docs/cli/setup-cli.mdx new file mode 100644 index 0000000000..5a90ddb320 --- /dev/null +++ b/docs/cli/setup-cli.mdx @@ -0,0 +1,144 @@ +--- +id: setup-cli +title: Set up the Temporal CLI +sidebar_label: Set up the CLI +slug: /cli/setup-cli +description: Install the Temporal CLI and run a local development server. +keywords: + - Temporal CLI + - Install CLI + - Development server + - Run dev server +--- + +The Temporal CLI is a command-line tool for interacting with the Temporal Service. +It helps you manage, monitor, and debug Temporal applications. +You can also use it to run a local development server and interact with Temporal Applications from the command line. + +With the Temporal CLI, you can: + +- Run a local Temporal Service for development +- Start Workflow Executions on any Temporal Service (local, self-hosted, or Temporal Cloud) +- Interact with running Workflows +- Inspect the state of Workflows and Activities +- Manage Namespaces, Schedules, and Task Queues +- Monitor and debug application behavior + +## Install the CLI + +The CLI is available for macOS, Linux, and Windows. + + + + + +Install with Homebrew: + +```bash +brew install temporal +``` + +Or download from the CDN: + +- [Darwin amd64](https://temporal.download/cli/archive/latest?platform=darwin&arch=amd64) +- [Darwin arm64](https://temporal.download/cli/archive/latest?platform=darwin&arch=arm64) + +Extract the archive and add the `temporal` binary to your `PATH`. + + + + + +Install with Homebrew (if available): + +```bash +brew install temporal +``` + +Or download from the CDN: + +- [Linux amd64](https://temporal.download/cli/archive/latest?platform=linux&arch=amd64) +- [Linux arm64](https://temporal.download/cli/archive/latest?platform=linux&arch=arm64) + +Extract the archive and add the `temporal` binary to your `PATH`. + + + + + +Download from the CDN: + +- [Windows amd64](https://temporal.download/cli/archive/latest?platform=windows&arch=amd64) +- [Windows arm64](https://temporal.download/cli/archive/latest?platform=windows&arch=arm64) + +Extract the archive and add the `temporal.exe` binary to your `PATH`. + + + + + +## Run the development server + +The CLI includes a local Temporal development service for fast feedback while building your application. + +Start the server: + +```bash +temporal server start-dev \ + --db-filename path/to/local-persistent-store +``` + +View available options: + +```bash +temporal server start-dev \ + --help +``` + +### What the local server provides + +- A local instance of the Temporal Service +- Automatic startup of the Web UI +- A default Namespace +- Optional persistence using SQLite + +Omitting `--db-filename` uses an in-memory database. This speeds up testing but does not persist Workflow data between sessions. + +### Access the Web UI + +- Temporal Service: `localhost:7233` +- Web UI: [http://localhost:8233](http://localhost:8233) + +:::tip +The CLI works with all Temporal SDKs. +Use it to develop and test your application before deploying to production. +::: + +## Getting CLI help + +From the command line: + +``` +temporal --help +``` + +For example: + +- `temporal --help` +- `temporal workflow --help` +- `temporal workflow delete --help` + +Available commands + +| Command | Description | +|--------------|--------------------------------------------------| +| [**activity**](/cli/activity) | Complete, update, pause, unpause, reset or fail an Activity | +| [**batch**](/cli/batch) | Manage running batch jobs | +| [**completion**](/cli/cmd-options) | Generate the autocompletion script for the specified shell | +| [**env**](/cli/env) | Manage environments | +| [**operator**](/cli/operator) | Manage Temporal deployments | +| [**schedule**](/cli/schedule) | Perform operations on Schedules | +| [**server**](/cli/server) | Run Temporal Server | +| [**task-queue**](/cli/task-queue) | Manage Task Queues | +| [**worker**](/cli/worker) | Read or update Worker state | +| [**workflow**](/cli/workflow) | Start, list, and operate on Workflows | diff --git a/sidebars.js b/sidebars.js index 9455906e14..2bc8165630 100644 --- a/sidebars.js +++ b/sidebars.js @@ -489,6 +489,7 @@ module.exports = { id: "cli/index", }, items: [ + "cli/setup-cli", "cli/activity", "cli/batch", "cli/cmd-options", From 46a76fc7c1dc580e723149474acba8262f802b76 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 28 Apr 2025 21:07:24 +0000 Subject: [PATCH 14/14] CI: Automatic .md and .mdx formatting --- docs/cli/setup-cli.mdx | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/cli/setup-cli.mdx b/docs/cli/setup-cli.mdx index 5a90ddb320..a8284c6cb9 100644 --- a/docs/cli/setup-cli.mdx +++ b/docs/cli/setup-cli.mdx @@ -130,15 +130,15 @@ For example: Available commands -| Command | Description | -|--------------|--------------------------------------------------| -| [**activity**](/cli/activity) | Complete, update, pause, unpause, reset or fail an Activity | -| [**batch**](/cli/batch) | Manage running batch jobs | -| [**completion**](/cli/cmd-options) | Generate the autocompletion script for the specified shell | -| [**env**](/cli/env) | Manage environments | -| [**operator**](/cli/operator) | Manage Temporal deployments | -| [**schedule**](/cli/schedule) | Perform operations on Schedules | -| [**server**](/cli/server) | Run Temporal Server | -| [**task-queue**](/cli/task-queue) | Manage Task Queues | -| [**worker**](/cli/worker) | Read or update Worker state | -| [**workflow**](/cli/workflow) | Start, list, and operate on Workflows | +| Command | Description | +| ---------------------------------- | ----------------------------------------------------------- | +| [**activity**](/cli/activity) | Complete, update, pause, unpause, reset or fail an Activity | +| [**batch**](/cli/batch) | Manage running batch jobs | +| [**completion**](/cli/cmd-options) | Generate the autocompletion script for the specified shell | +| [**env**](/cli/env) | Manage environments | +| [**operator**](/cli/operator) | Manage Temporal deployments | +| [**schedule**](/cli/schedule) | Perform operations on Schedules | +| [**server**](/cli/server) | Run Temporal Server | +| [**task-queue**](/cli/task-queue) | Manage Task Queues | +| [**worker**](/cli/worker) | Read or update Worker state | +| [**workflow**](/cli/workflow) | Start, list, and operate on Workflows |