diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml new file mode 100644 index 0000000000..b117e23ed4 --- /dev/null +++ b/.github/workflows/update-cli-docs.yml @@ -0,0 +1,87 @@ +name: 'CLI Docs Update' + +on: + workflow_dispatch: + inputs: + 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' + 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 + permissions: + contents: write + pull-requests: write + 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 docs repo + uses: actions/checkout@v4 + with: + persist-credentials: true + token: ${{ steps.generate_token.outputs.token }} + path: docs + ref: main + + - name: Checkout CLI repo + uses: actions/checkout@v4 + with: + path: cli + ref: ${{ github.event.inputs.cli_release_tag }} + submodules: recursive + persist-credentials: true + token: ${{ steps.generate_token.outputs.token }} + repository: temporalio/cli + + - name: Setup Go + uses: actions/setup-go@v4 + with: + go-version: '1.22' + + - name: Generate CLI docs + working-directory: cli/temporalcli/internal/cmd/gen-docs + run: | + go run . + + - name: Publish generated docs to documentation repo + env: + GH_TOKEN: ${{ github.token }} + working-directory: docs + run: | + set -ex + + git config user.name "${{ github.event.inputs.commit_author }}" + git config user.email "${{ github.event.inputs.commit_author_email }}" + + 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 "$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" diff --git a/docs/cli/activity.mdx b/docs/cli/activity.mdx index b78ab9df5b..e396aa52ef 100644 --- a/docs/cli/activity.mdx +++ b/docs/cli/activity.mdx @@ -7,12 +7,12 @@ 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 @@ -22,299 +22,925 @@ tags: - 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. -- [--activity-id](/cli/cmd-options#activity-id) +**--color** _string-enum_ -- [--address](/cli/cmd-options#address) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--codec-auth](/cli/cmd-options#codec-auth) +**--command-timeout** _duration_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +The command execution timeout. 0s means no timeout. -- [--color](/cli/cmd-options#color) +**--env** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Active environment name (`ENV`). (default "default") -- [--env](/cli/cmd-options#env) +**--env-file** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--identity](/cli/cmd-options#identity) +**--grpc-meta** _string[]_ -- [--namespace](/cli/cmd-options#namespace) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--result](/cli/cmd-options#result) +**--log-format** _string-enum_ -- [--run-id](/cli/cmd-options#run-id) +Log format. Accepted values: text, json. (default "text") -- [--tls](/cli/cmd-options#tls) +**--log-level** _string-enum_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-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-cert-path](/cli/cmd-options#tls-cert-path) +**--namespace**, **-n** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Temporal Service Namespace. (default "default") -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--no-json-shorthand-payloads** _bool_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Raw payload output, even if the JSON option was used. -- [--workflow-id](/cli/cmd-options#workflow-id) +**--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. ## 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_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _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) +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. -Pausing an Activity means: +If the Activity is not currently running (e.g. because it previously +failed), it will not be run again until it is unpaused. -- 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. +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. -If Activity Type is provided and multiple pending Activities of the provided type exist, all of them will be 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. -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. +Specify the Activity and Workflow IDs: + +``` +temporal activity pause \ + --activity-id YourActivityId \ + --workflow-id YourWorkflowId +``` -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. + +**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. + +## 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 +``` + +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. + +**--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. -Command will fail with a `NotFound` error if there is no pending Activity with the provided ID or type. +Use `--reset-heartbeat` to reset the Activity's heartbeats. + +Activities can be specified by their Activity ID or Activity Type. +One of those parameters must be provided. 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..2bc48b9507 100644 --- a/docs/cli/batch.mdx +++ b/docs/cli/batch.mdx @@ -17,187 +17,368 @@ tags: - 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 -**Which batch operations can be performed by the Temporal CLI?** +Show the progress of an ongoing batch job. Pass a valid job ID to display its +information: -There are three types of Batch Jobs: +``` +temporal batch describe \ + --job-id YourJobId +``` -- 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. +Use the following options to change the behavior of this command. -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. +**Flags:** -These commands will directly impact the Workflows you target, so it's important to use them judiciously. +**--job-id** _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. +Batch job ID. Required. -To Cancel Workflows: +**Global Flags:** -```command -temporal workflow cancel \ - --query 'ExecutionStatus = "Running" AND WorkflowType="YourWorkflow"' \ - --reason "Testing" -``` +**--address** _string_ -To Signal Workflows: +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -```command -temporal workflow signal \ - --workflow-id MyWorkflowId \ - --name MySignal \ - --input '{"Input": "As-JSON"}' \ - --query 'ExecutionStatus = "Running" AND WorkflowType="YourWorkflow"' \ - --reason "Testing" -``` +**--api-key** _string_ -To Terminate Workflows: +API key for request. -```command -temporal workflow terminate \ - --query 'ExecutionStatus = "Running" AND WorkflowType="YourWorkflow"' \ - --reason "Testing" -``` +**--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_ -A successfully started Batch job will return a Job ID. -Use this Job ID to execute other actions on the Batch job. +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") + +**--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_ -- [--job-id](/cli/cmd-options#job-id) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--namespace](/cli/cmd-options#namespace) +**--tls-ca-path** _string_ -- [--output](/cli/cmd-options#output) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--time-format](/cli/cmd-options#time-format) +**--tls-cert-data** _string_ -- [--tls](/cli/cmd-options#tls) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--tls-cert-path** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls-disable-host-verification** _bool_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Disable TLS host-name verification. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--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_ -- [--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_ -- [--job-id](/cli/cmd-options#job-id) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--namespace](/cli/cmd-options#namespace) +**--tls-disable-host-verification** _bool_ -- [--reason](/cli/cmd-options#reason) +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. diff --git a/docs/cli/env.mdx b/docs/cli/env.mdx index 8be0319830..65b6719012 100644 --- a/docs/cli/env.mdx +++ b/docs/cli/env.mdx @@ -19,162 +19,504 @@ tags: - 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_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ -Use `env ` alongside other commands to point the Temporal CLI at a different Temporal Server instance. +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_ -The `temporal env delete` command deletes a given environment or environmental property. +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -`temporal env delete [environment or property]` +**--time-format** _string-enum_ -Pass a valid [Namespace](/namespaces) into the command to delete an environment and its saved values. +Time format. Accepted values: relative, iso, raw. (default "relative") -`temporal env delete local` +**--tls** _bool_ -Use the following options to change the 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. + +**--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_ -- [--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_ -- [--output](/cli/cmd-options#output) +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. diff --git a/docs/cli/operator.mdx b/docs/cli/operator.mdx index a013c50977..43825158b2 100644 --- a/docs/cli/operator.mdx +++ b/docs/cli/operator.mdx @@ -2,7 +2,7 @@ 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]". +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 @@ -37,1007 +37,2555 @@ tags: - Temporal CLI --- -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 output of this command. +Use the following options to change the behavior of this command. -- [--address](/cli/cmd-options#address) +**Flags:** -- [--codec-auth](/cli/cmd-options#codec-auth) +**--detail** _bool_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Show history shard count and Cluster/Service version information. -- [--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. -- [--namespace](/cli/cmd-options#namespace) +**--codec-auth** _string_ -- [--output](/cli/cmd-options#output) +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") -### health +**--command-timeout** _duration_ -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. +The command execution timeout. 0s means no timeout. -Use the following options to change the behavior and output 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_ -- [--tls](/cli/cmd-options#tls) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--namespace**, **-n** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Temporal Service Namespace. (default "default") -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--no-json-shorthand-payloads** _bool_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Raw payload output, even if the JSON option was used. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--output**, **-o** _string-enum_ -### list +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -The `temporal operator cluster list` command prints a list of all remote [Clusters](/temporal-service) on the system. +**--time-format** _string-enum_ -`temporal operator cluster list` +Time format. Accepted values: relative, iso, raw. (default "relative") -Use the following options to change the command's behavior. +**--tls** _bool_ -- [--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_ -- [--fields](/cli/cmd-options#fields) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--tls-cert-path** _string_ -- [--limit](/cli/cmd-options#limit) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--namespace](/cli/cmd-options#namespace) +**--tls-disable-host-verification** _bool_ -- [--no-pager](/cli/cmd-options#no-pager) +Disable TLS host-name verification. -- [--output](/cli/cmd-options#output) +**--tls-key-data** _string_ -- [--pager](/cli/cmd-options#pager) +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-path](/cli/cmd-options#tls-ca-path) +**--tls-server-name** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Override target TLS server name. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +### health -- [--tls-key-path](/cli/cmd-options#tls-key-path) +View information about the health of a Temporal Service: -- [--tls-server-name](/cli/cmd-options#tls-server-name) +``` +temporal operator cluster health +``` -### remove +Use the following options to change the behavior of this command. -The `temporal operator cluster remove` command removes a remote [Cluster](/temporal-service) from the system. +**Global Flags:** -`temporal operator cluster remove --name=SomeCluster` +**--address** _string_ -Use the following options to change the command's behavior. +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--address](/cli/cmd-options#address) +**--api-key** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +API key for request. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--codec-auth** _string_ -- [--color](/cli/cmd-options#color) +Authorization header for Codec Server requests. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--codec-endpoint** _string_ -- [--env](/cli/cmd-options#env) +Remote Codec Server endpoint. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--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_ -- [--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_ -### system +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -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). +**--grpc-meta** _string[]_ -`temporal operator cluster system` +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 this command's behavior. +**--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_ -- [--fields](/cli/cmd-options#fields) +Raw payload output, even if the JSON option was used. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--output**, **-o** _string-enum_ -- [--namespace](/cli/cmd-options#namespace) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--output](/cli/cmd-options#output) +**--time-format** _string-enum_ -- [--tls](/cli/cmd-options#tls) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--tls** _bool_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--tls-ca-data** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--tls-ca-path** _string_ -### upsert +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 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"` +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: -Upserting can also be used to enable or disabled cross-cluster connection. -`temporal operator cluster upsert --enable-connection=true` +``` +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_ -The `temporal operator namespace update` command updates a [Namespace](/namespaces). +Override target TLS server name. -Namespaces can be assigned a different active [Cluster](/temporal-service). -`temporal operator namespace update --active-cluster=NewActiveCluster` +### system -Namespaces can also be promoted to global Namespaces. -`temporal operator namespace --promote-global=true` +Show Temporal Server information for Temporal Clusters (Service): Server +version, scheduling support, and more. This information helps diagnose +problems with the Temporal Server. -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"` +The command defaults to the local Service. Otherwise, use the +`--frontend-address` option to specify a Cluster (Service) endpoint: -:::note +``` +temporal operator cluster system \ + --frontend-address "YourRemoteEndpoint:YourRemotePort" +``` -The Namespace needs to be the last argument passed in your command. -For example, `temporal operator namespace update --retention 180 your_namespace`. +Use the following options to change the behavior of this command. -::: +**Global Flags:** -Use the options listed below to change the command's behavior. +**--address** _string_ -- [--active-cluster](/cli/cmd-options#active-cluster) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--address](/cli/cmd-options#address) +**--api-key** _string_ -- [--cluster](/cli/cmd-options#cluster) +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. -- [--data](/cli/cmd-options#data) +**--codec-header** _string[]_ -- [--description](/cli/cmd-options#description) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--email](/cli/cmd-options#email) +**--color** _string-enum_ -- [--env](/cli/cmd-options#env) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--command-timeout** _duration_ -- [--history-archival-state](/cli/cmd-options#history-archival-state) +The command execution timeout. 0s means no timeout. -- [--history-uri](/cli/cmd-options#history-uri) +**--env** _string_ -- [--namespace](/cli/cmd-options#namespace) +Active environment name (`ENV`). (default "default") -- [--promote-global](/cli/cmd-options#promote-global) +**--env-file** _string_ -- [--retention](/cli/cmd-options#retention) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--tls](/cli/cmd-options#tls) +**--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-path](/cli/cmd-options#tls-cert-path) +**--log-format** _string-enum_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +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") -- [--verbose](/cli/cmd-options#verbose) +**--namespace**, **-n** _string_ -- [--visibility-archival-state](/cli/cmd-options#visibility-archival-state) +Temporal Service Namespace. (default "default") -- [--visibility-uri](/cli/cmd-options#visibility-uri) +**--no-json-shorthand-payloads** _bool_ -## nexus +Raw payload output, even if the JSON option was used. -These commands manage Nexus resources. +**--output**, **-o** _string-enum_ -Nexus commands follow this syntax: +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -``` -temporal operator nexus [command] [subcommand] [options] -``` +**--time-format** _string-enum_ -### endpoint +Time format. Accepted values: relative, iso, raw. (default "relative") -These commands manage Nexus Endpoints. +**--tls** _bool_ -Nexus Endpoint commands follow this syntax: +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -``` -temporal operator nexus endpoint [command] [options] -``` +**--tls-ca-data** _string_ -#### create +Data for server CA certificate. Can't be used with --tls-ca-path. -Create a Nexus Endpoint on the Server. +**--tls-ca-path** _string_ -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. +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. -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_ -- [--address](/cli/cmd-options#address) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--api-key](/cli/cmd-options#api-key) +**--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. -- [--env-file](/cli/cmd-options#env-file) +**--tls-ca-path** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--log-format](/cli/cmd-options#log-format) +**--tls-cert-data** _string_ -- [--log-level](/cli/cmd-options#log-level) +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. -- [--no-json-shorthand-payloads](/cli/cmd-options#no-json-shorthand-payloads) +**--tls-disable-host-verification** _bool_ -- [--output](/cli/cmd-options#output) +Disable TLS host-name verification. -- [--time-format](/cli/cmd-options#time-format) +**--tls-key-data** _string_ -- [--tls](/cli/cmd-options#tls) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls-ca-data](/cli/cmd-options#tls-ca-data) +**--tls-key-path** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls-cert-data](/cli/cmd-options#tls-cert-data) +**--tls-server-name** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Override target TLS server name. + +## namespace -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Manage Temporal Cluster (Service) Namespaces: -- [--tls-key-data](/cli/cmd-options#tls-key-data) +``` +temporal operator namespace [command] [command options] +``` -- [--tls-key-path](/cli/cmd-options#tls-key-path) +For example: -- [--tls-server-name](/cli/cmd-options#tls-server-name) +``` +temporal operator namespace create \ + --namespace YourNewNamespaceName +``` -#### get +### create -Get a Nexus Endpoint by name from the Server. +Create a new Namespace on the Temporal Service: ``` -temporal operator nexus endpoint get --name your-endpoint +temporal operator namespace create \ + --namespace YourNewNamespaceName \ + [options] ``` +Create a Namespace with multi-region data replication: + +``` +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_ + +Time format. Accepted values: relative, iso, raw. (default "relative") -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. +**--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. -- [--fields](/cli/cmd-options#fields) -- [--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_ -- [--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_ -- [--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_ -- [--type](/cli/cmd-options#type) +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 workflow list --query`. +``` +temporal operator namespace list +``` -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) +**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_ -- [--output](/cli/cmd-options#output) +Remote Codec Server endpoint. -- [--tls](/cli/cmd-options#tls) +**--codec-header** _string[]_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--color** _string-enum_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--command-timeout** _duration_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +The command execution timeout. 0s means no timeout. -### remove +**--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 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") -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. +**--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_ -- [--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_ -- [--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_ -- [--yes](/cli/cmd-options#yes) +Override target TLS server name. diff --git a/docs/cli/schedule.mdx b/docs/cli/schedule.mdx index ed9b453be6..6fbfa1fd0e 100644 --- a/docs/cli/schedule.mdx +++ b/docs/cli/schedule.mdx @@ -24,521 +24,1306 @@ tags: - Schedules --- -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. -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. +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. + +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_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ -Use the following options to change this command's behavior. +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_ -- [--end-time](/cli/cmd-options#end-time) +Log format. Accepted values: text, json. (default "text") -- [--env](/cli/cmd-options#env) +**--log-level** _string-enum_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +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_ -- [--overlap-policy](/cli/cmd-options#overlap-policy) +Temporal Service Namespace. (default "default") -- [--schedule-id](/cli/cmd-options#schedule-id) +**--no-json-shorthand-payloads** _bool_ -- [--start-time](/cli/cmd-options#start-time) +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. + +**--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' + --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_ + +Time format. Accepted values: relative, iso, raw. (default "relative") -Any combination of `--calendar`, `--interval`, and `--cron` is supported. -Traditional cron strings, along with `CronSchedule` features, are also supported. +**--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[]_ -Use the following options to change the command's behavior. +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--address](/cli/cmd-options#address) +**--color** _string-enum_ -- [--calendar](/cli/cmd-options#calendar) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--catchup-window](/cli/cmd-options#catchup-window) +**--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_ -- [--cron](/cli/cmd-options#cron) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--end-time](/cli/cmd-options#end-time) +**--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. -- [--execution-timeout](/cli/cmd-options#execution-timeout) +**--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") -- [--interval](/cli/cmd-options#interval) +**--namespace**, **-n** _string_ -- [--jitter](/cli/cmd-options#jitter) +Temporal Service Namespace. (default "default") -- [--max-field-length](/cli/cmd-options#max-field-length) +**--no-json-shorthand-payloads** _bool_ -- [--memo](/cli/cmd-options#memo) +Raw payload output, even if the JSON option was used. -- [--memo-file](/cli/cmd-options#memo-file) +**--output**, **-o** _string-enum_ -- [--namespace](/cli/cmd-options#namespace) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--notes](/cli/cmd-options#notes) +**--time-format** _string-enum_ -- [--overlap-policy](/cli/cmd-options#overlap-policy) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--pause](/cli/cmd-options#pause) +**--tls** _bool_ -- [--pause-on-failure](/cli/cmd-options#pause-on-failure) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--remaining-actions](/cli/cmd-options#remaining-actions) +**--tls-ca-data** _string_ -- [--run-timeout](/cli/cmd-options#run-timeout) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--schedule-id](/cli/cmd-options#schedule-id) +**--tls-ca-path** _string_ -- [--search-attribute](/cli/cmd-options#search-attribute) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--start-time](/cli/cmd-options#start-time) +**--tls-cert-data** _string_ -- [--task-queue](/cli/cmd-options#task-queue) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--task-timeout](/cli/cmd-options#task-timeout) +**--tls-cert-path** _string_ -- [--time-zone](/cli/cmd-options#time-zone) +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. -- [--workflow-id](/cli/cmd-options#workflow-id) +**--tls-server-name** _string_ -- [--workflow-type](/cli/cmd-options#workflow-type) +Override target TLS server name. diff --git a/docs/cli/server.mdx b/docs/cli/server.mdx index 6593e52e64..a6e52d78f9 100644 --- a/docs/cli/server.mdx +++ b/docs/cli/server.mdx @@ -15,42 +15,212 @@ tags: - Development Server --- -Server commands allow you to start and manage the [Temporal Server](/temporal-service/temporal-server) from the command line. +## start-dev -Currently, `cli` server functionality extends to starting the Server. +Run a development Temporal Server on your local system. -## start-dev ++------------------------------------------------------------------------+ +| 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 + +``` +temporal server start-dev +``` + +Add persistence for Workflow Executions across runs: -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 \ + --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): + +``` +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_ -- [--dynamic-config-value](/cli/cmd-options#dynamic-config-value) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--headless](/cli/cmd-options#headless) +**--tls-cert-data** _string_ -- [--ip](/cli/cmd-options#ip) +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. -- [--metrics-port](/cli/cmd-options#metrics-port) +**--tls-disable-host-verification** _bool_ -- [--namespace](/cli/cmd-options#namespace) +Disable TLS host-name verification. -- [--port](/cli/cmd-options#port) +**--tls-key-data** _string_ -- [--sqlite-pragma](/cli/cmd-options#sqlite-pragma) +Private certificate key data. Can't be used with --tls-key-path. -- [--ui-asset-path](/cli/cmd-options#ui-asset-path) +**--tls-key-path** _string_ -- [--ui-codec-endpoint](/cli/cmd-options#ui-codec-endpoint) +Path to x509 private key. Can't be used with --tls-key-data. -- [--ui-ip](/cli/cmd-options#ui-ip) +**--tls-server-name** _string_ -- [--ui-port](/cli/cmd-options#ui-port) +Override target TLS server name. diff --git a/docs/cli/setup-cli.mdx b/docs/cli/setup-cli.mdx new file mode 100644 index 0000000000..a8284c6cb9 --- /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/docs/cli/task-queue.mdx b/docs/cli/task-queue.mdx index cf7513b74a..de09d6529d 100644 --- a/docs/cli/task-queue.mdx +++ b/docs/cli/task-queue.mdx @@ -15,177 +15,2306 @@ tags: - 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. + +**--tls-cert-data** _string_ -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. +Data for x509 certificate. Can't be used with --tls-cert-path. -Information about the Task Queue can be returned to troubleshoot server issues. +**--tls-cert-path** _string_ -`temporal task-queue describe --task-queue=MyTaskQueue --task-queue-type="activity"` +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. + +**--output**, **-o** _string-enum_ -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. +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -Use the following options to change the command's behavior. +**--time-format** _string-enum_ -- [--address](/cli/cmd-options#address) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--codec-auth](/cli/cmd-options#codec-auth) +**--tls** _bool_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--color](/cli/cmd-options#color) +**--tls-ca-data** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--env](/cli/cmd-options#env) +**--tls-ca-path** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--namespace](/cli/cmd-options#namespace) +**--tls-cert-data** _string_ -- [--output](/cli/cmd-options#output) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--task-queue](/cli/cmd-options#task-queue) +**--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. ## 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. | ++-----------------------------------------------------------------------------+ + +Fetch sets of compatible Build IDs for specified Task Queues and display their +information: -- [--address](/cli/cmd-options#address) +``` +temporal task-queue get-build-ids \ + --task-queue YourTaskQueue +``` -- [--codec-auth](/cli/cmd-options#codec-auth) +This command is limited to Namespaces that support Worker versioning. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Use the following options to change the behavior of this command. -- [--color](/cli/cmd-options#color) +**Flags:** -- [--command-timeout](/cli/cmd-options#command-timeout) +**--max-sets** _int_ -- [--env](/cli/cmd-options#env) +Max return count. Use 1 for default major version. Use 0 for all sets. (default "0") -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--task-queue**, **-t** _string_ -- [--max-sets](/cli/cmd-options#max-sets) +Task Queue name. Required. -- [--namespace](/cli/cmd-options#namespace) +**Global Flags:** -- [--task-queue](/cli/cmd-options#task-queue) +**--address** _string_ -- [--tls](/cli/cmd-options#tls) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--api-key** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +API key for request. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--codec-auth** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Authorization header for Codec Server requests. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--codec-endpoint** _string_ -## get-build-id-reachability +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. -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. +**--tls-ca-data** _string_ -- [--address](/cli/cmd-options#address) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--build-id](/cli/cmd-options#build-id) +**--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. -- [--reachability-type](/cli/cmd-options#reachability-type) +**--tls-key-data** _string_ -- [--task-queue](/cli/cmd-options#task-queue) +Private certificate key data. Can't be used with --tls-key-path. -- [--tls](/cli/cmd-options#tls) +**--tls-key-path** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--tls-server-name** _string_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Override target TLS server name. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +## 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_ -- [--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") + +**--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..2264870c0b --- /dev/null +++ b/docs/cli/worker.mdx @@ -0,0 +1,1215 @@ +--- +id: 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: + - Temporal CLI +--- + +## 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..17786fd6b1 100644 --- a/docs/cli/workflow.mdx +++ b/docs/cli/workflow.mdx @@ -2,7 +2,7 @@ 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. +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,4053 @@ keywords: - workflow start - workflow terminate - workflow trace + - workflow update-options tags: - Temporal CLI - Workflows --- -[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[]_ + +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_ -- [--address](/cli/cmd-options#address) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--grpc-meta** _string[]_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--color](/cli/cmd-options#color) +**--log-format** _string-enum_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Log format. Accepted values: text, json. (default "text") -- [--env](/cli/cmd-options#env) +**--log-level** _string-enum_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +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_ -- [--query](/cli/cmd-options#query) +Temporal Service Namespace. (default "default") -- [--reason](/cli/cmd-options#reason) +**--no-json-shorthand-payloads** _bool_ -- [--run-id](/cli/cmd-options#run-id) +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_ -- [--yes](/cli/cmd-options#yes) +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") + +**--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") -- [--codec-auth](/cli/cmd-options#codec-auth) +**--command-timeout** _duration_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +The command execution timeout. 0s means no timeout. -- [--color](/cli/cmd-options#color) +**--env** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Active environment name (`ENV`). (default "default") -- [--env](/cli/cmd-options#env) +**--env-file** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--namespace](/cli/cmd-options#namespace) +**--grpc-meta** _string[]_ -- [--query](/cli/cmd-options#query) +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") + +**--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_ + +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_ -Use the following options to change the command's behavior. +Log format. Accepted values: text, json. (default "text") -- [--address](/cli/cmd-options#address) +**--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_ -- [--env](/cli/cmd-options#env) +Raw payload output, even if the JSON option was used. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--output**, **-o** _string-enum_ -- [--namespace](/cli/cmd-options#namespace) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--query](/cli/cmd-options#query) +**--time-format** _string-enum_ -- [--reason](/cli/cmd-options#reason) +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_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--yes](/cli/cmd-options#yes) +**--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:** + +**--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. -`temporal workflow describe --workflow-id=meaningful-business-id` +**--codec-header** _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. +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -`temporal workflow describe --workflow-id=meaningful-business-id --raw=true --reset-points=true` +**--color** _string-enum_ -Use the following command options to change the information returned by this command. +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_ -- [--env](/cli/cmd-options#env) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--grpc-meta** _string[]_ -- [--namespace](/cli/cmd-options#namespace) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--raw](/cli/cmd-options#raw) +**--log-format** _string-enum_ -- [--reset-points](/cli/cmd-options#reset-points) +Log format. Accepted values: text, json. (default "text") -- [--run-id](/cli/cmd-options#run-id) +**--log-level** _string-enum_ -- [--tls](/cli/cmd-options#tls) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--namespace**, **-n** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Temporal Service Namespace. (default "default") -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--no-json-shorthand-payloads** _bool_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Raw payload output, even if the JSON option was used. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--output**, **-o** _string-enum_ -- [--workflow-id](/cli/cmd-options#workflow-id) +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) +## execute-update-with-start -- [--env](/cli/cmd-options#env) +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. -- [--event-id](/cli/cmd-options#event-id) +Experimental. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +``` +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"}' +``` -- [--namespace](/cli/cmd-options#namespace) +Use the following options to change the behavior of this command. -- [--reapply-type](/cli/cmd-options#reapply-type) +**Flags:** -- [--reason](/cli/cmd-options#reason) +**--cron** _string_ -- [--run-id](/cli/cmd-options#run-id) +Cron schedule for the Workflow. Deprecated. Use Schedules instead. -- [--tls](/cli/cmd-options#tls) +**--execution-timeout** _duration_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--fail-existing** _bool_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Fail if the Workflow already exists. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--id-conflict-policy** _string-enum_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +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. -- [--type](/cli/cmd-options#type) +**--id-reuse-policy** _string-enum_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning. -## reset-batch +**--input**, **-i** _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). +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. -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. +**--input-base64** _bool_ -`temporal workflow reset-batch --input-file=MyInput --input-separator="\t"` +Assume inputs are base64-encoded and attempt to decode them. -Workflow Executions can also be queried by a [List Filter](/list-filter). -`temporal workflow reset-batch --query=MyListFilter` +**--input-file** _string[]_ -Use the following options to change reset behavior. +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. -- [--address](/cli/cmd-options#address) +**--input-meta** _string[]_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--memo** _string[]_ -- [--color](/cli/cmd-options#color) +Memo using 'KEY="VALUE"' pairs. Use JSON values. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--run-id**, **-r** _string_ -- [--dry-run](/cli/cmd-options#dry-run) +Run ID. If unset, looks for an Update against the currently-running Workflow Execution. -- [--env](/cli/cmd-options#env) +**--run-timeout** _duration_ -- [--exclude-file](/cli/cmd-options#exclude-file) +Fail a Workflow Run if it lasts longer than `DURATION`. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--search-attribute** _string[]_ -- [--input-file](/cli/cmd-options#input-file) +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. -- [--input-parallelism](/cli/cmd-options#input-parallelism) +**--start-delay** _duration_ -- [--input-separator](/cli/cmd-options#input-separator) +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. -- [--namespace](/cli/cmd-options#namespace) +**--static-details** _string_ -- [--non-deterministic](/cli/cmd-options#non-deterministic) +Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines. -- [--query](/cli/cmd-options#query) +:::note -- [--reason](/cli/cmd-options#reason) +Option is experimental. -- [--skip-base-is-not-current](/cli/cmd-options#skip-base-is-not-current) +::: -- [--skip-current-open](/cli/cmd-options#skip-current-open) +**--static-summary** _string_ -- [--tls](/cli/cmd-options#tls) +Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line. -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +:::note -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +Option is experimental. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +::: -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--task-queue**, **-t** _string_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Workflow Task queue. Required. -- [--type](/cli/cmd-options#type) +**--task-timeout** _duration_ -## show +Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s") -The `temporal workflow show` command provides the [Event History](/workflow-execution/event#event-history) for a [Workflow Execution](/workflow-execution). +**--type** _string_ -Use the following options to change the behavior of this command. +Workflow Type name. Required. -- [--address](/cli/cmd-options#address) +**--update-first-execution-run-id** _string_ -- [--codec-auth](/cli/cmd-options#codec-auth) +Parent Run ID. The update is sent to the last Workflow Execution in the chain started with this Run ID. -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--update-id** _string_ -- [--color](/cli/cmd-options#color) +Update ID. If unset, defaults to a UUID. -- [--command-timeout](/cli/cmd-options#command-timeout) +**--update-input** _string[]_ -- [--env](/cli/cmd-options#env) +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. -- [--fields](/cli/cmd-options#fields) +**--update-input-base64** _bool_ -- [--follow](/cli/cmd-options#follow) +Assume update inputs are base64-encoded and attempt to decode them. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--update-input-file** _string[]_ -- [--limit](/cli/cmd-options#limit) +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. -- [--max-field-length](/cli/cmd-options#max-field-length) +**--update-input-meta** _string[]_ -- [--namespace](/cli/cmd-options#namespace) +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. -- [--no-pager](/cli/cmd-options#no-pager) +**--update-name** _string_ -- [--output](/cli/cmd-options#output) +Update name. Required. -- [--pager](/cli/cmd-options#pager) +**--workflow-id**, **-w** _string_ -- [--reset-points](/cli/cmd-options#reset-points) +Workflow ID. If not supplied, the Service generates a unique ID. -- [--run-id](/cli/cmd-options#run-id) +**Global Flags:** -- [--time-format](/cli/cmd-options#time-format) +**--address** _string_ -- [--tls](/cli/cmd-options#tls) +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +**--api-key** _string_ -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +API key for request. -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +**--codec-auth** _string_ -- [--tls-key-path](/cli/cmd-options#tls-key-path) +Authorization header for Codec Server requests. -- [--tls-server-name](/cli/cmd-options#tls-server-name) +**--codec-endpoint** _string_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Remote Codec Server endpoint. -## signal +**--codec-header** _string[]_ -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). +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") -- [--codec-auth](/cli/cmd-options#codec-auth) +**--command-timeout** _duration_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +The command execution timeout. 0s means no timeout. -- [--color](/cli/cmd-options#color) +**--env** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Active environment name (`ENV`). (default "default") -- [--env](/cli/cmd-options#env) +**--env-file** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--input](/cli/cmd-options#input) +**--grpc-meta** _string[]_ -- [--input-file](/cli/cmd-options#input-file) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--name](/cli/cmd-options#name) +**--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_ -## stack +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -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-ca-data** _string_ -Use the following options to change the command's behavior. +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_ -- [--input](/cli/cmd-options#input) +Disable TLS host-name verification. -- [--input-file](/cli/cmd-options#input-file) +**--tls-key-data** _string_ -- [--namespace](/cli/cmd-options#namespace) +Private certificate key data. Can't be used with --tls-key-path. -- [--reject-condition](/cli/cmd-options#reject-condition) +**--tls-key-path** _string_ -- [--run-id](/cli/cmd-options#run-id) +Path to x509 private key. Can't be used with --tls-key-data. -- [--tls](/cli/cmd-options#tls) +**--tls-server-name** _string_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Override target TLS server name. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +## fix-history-json -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Reserialize an Event History JSON file: -- [--tls-key-path](/cli/cmd-options#tls-key-path) +``` +temporal workflow fix-history-json \ + --source /path/to/original.json \ + --target /path/to/reserialized.json +``` -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Use the following options to change the behavior of this command. -- [--workflow-id](/cli/cmd-options#workflow-id) +**Flags:** -## start +**--source**, **-s** _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). +Path to the original file. Required. -`temporal workflow start --task-queue=MyTaskQueue --type=MyWorkflow` +**--target**, **-t** _string_ -Use the following command options to change how the Workflow Execution behaves upon starting. +Path to the results file. When omitted, output is sent to stdout. -- [--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. -- [--cron](/cli/cmd-options#cron) +**--codec-auth** _string_ -- [--env](/cli/cmd-options#env) +Authorization header for Codec Server requests. -- [--execution-timeout](/cli/cmd-options#execution-timeout) +**--codec-endpoint** _string_ -- [--fields](/cli/cmd-options#fields) +Remote Codec Server endpoint. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--codec-header** _string[]_ -- [--id-reuse-policy](/cli/cmd-options#id-reuse-policy) +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--input](/cli/cmd-options#input) +**--color** _string-enum_ -- [--input-file](/cli/cmd-options#input-file) +Output coloring. Accepted values: always, never, auto. (default "auto") -- [--limit](/cli/cmd-options#limit) +**--command-timeout** _duration_ -- [--max-field-length](/cli/cmd-options#max-field-length) +The command execution timeout. 0s means no timeout. -- [--memo](/cli/cmd-options#memo) +**--env** _string_ -- [--memo-file](/cli/cmd-options#memo-file) +Active environment name (`ENV`). (default "default") -- [--namespace](/cli/cmd-options#namespace) +**--env-file** _string_ -- [--no-pager](/cli/cmd-options#no-pager) +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. -- [--output](/cli/cmd-options#output) +**--grpc-meta** _string[]_ -- [--pager](/cli/cmd-options#pager) +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. -- [--run-timeout](/cli/cmd-options#run-timeout) +**--log-format** _string-enum_ -- [--search-attribute](/cli/cmd-options#search-attribute) +Log format. Accepted values: text, json. (default "text") -- [--start-delay](/cli/cmd-options#start-delay) +**--log-level** _string-enum_ -- [--task-queue](/cli/cmd-options#task-queue) +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") -- [--task-timeout](/cli/cmd-options#task-timeout) +**--namespace**, **-n** _string_ -- [--time-format](/cli/cmd-options#time-format) +Temporal Service Namespace. (default "default") -- [--tls](/cli/cmd-options#tls) +**--no-json-shorthand-payloads** _bool_ -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +Raw payload output, even if the JSON option was used. -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +**--output**, **-o** _string-enum_ -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -- [--tls-key-path](/cli/cmd-options#tls-key-path) +**--time-format** _string-enum_ -- [--tls-server-name](/cli/cmd-options#tls-server-name) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--type](/cli/cmd-options#type) +**--tls** _bool_ -- [--workflow-id](/cli/cmd-options#workflow-id) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -## terminate +**--tls-ca-data** _string_ -The `temporal workflow terminate` command terminates a [Workflow Execution](/workflow-execution) +Data for server CA certificate. Can't be used with --tls-ca-path. -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-ca-path** _string_ -Workflow terminations require a valid [Workflow ID](/workflow-execution/workflowid-runid#workflow-id) to function. -`temporal workflow terminate --workflow-id=meaningful-business-id` +Path to server CA certificate. Can't be used with --tls-ca-data. -Use the following options to change termination behavior. +**--tls-cert-data** _string_ -- [--address](/cli/cmd-options#address) +Data for x509 certificate. Can't be used with --tls-cert-path. -- [--codec-auth](/cli/cmd-options#codec-auth) +**--tls-cert-path** _string_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Path to x509 certificate. Can't be used with --tls-cert-data. -- [--color](/cli/cmd-options#color) +**--tls-disable-host-verification** _bool_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Disable TLS host-name verification. -- [--env](/cli/cmd-options#env) +**--tls-key-data** _string_ -- [--grpc-meta](/cli/cmd-options#grpc-meta) +Private certificate key data. Can't be used with --tls-key-path. -- [--namespace](/cli/cmd-options#namespace) +**--tls-key-path** _string_ -- [--query](/cli/cmd-options#query) +Path to x509 private key. Can't be used with --tls-key-data. -- [--reason](/cli/cmd-options#reason) +**--tls-server-name** _string_ -- [--run-id](/cli/cmd-options#run-id) +Override target TLS server name. -- [--tls](/cli/cmd-options#tls) +## list -- [--tls-ca-path](/cli/cmd-options#tls-ca-path) +List Workflow Executions. The optional `--query` limits the output to +Workflows matching a Query: -- [--tls-cert-path](/cli/cmd-options#tls-cert-path) +``` +temporal workflow list \ + --query YourQuery` +``` -- [--tls-disable-host-verification](/cli/cmd-options#tls-disable-host-verification) +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. -- [--tls-key-path](/cli/cmd-options#tls-key-path) +View a list of archived Workflow Executions: -- [--tls-server-name](/cli/cmd-options#tls-server-name) +``` +temporal workflow list \ + --archived +``` -- [--workflow-id](/cli/cmd-options#workflow-id) +Use the following options to change the behavior of this command. -- [--yes](/cli/cmd-options#yes) +**Flags:** -## trace +**--archived** _bool_ -The `temporal workflow trace` command tracks the progress of a [Workflow Execution](/workflow-execution) and any [Child Workflows](/child-workflows) it generates. +Limit output to archived Workflow Executions. -Use the following options to change the command's behavior. +:::note -- [--address](/cli/cmd-options#address) +Option is experimental. -- [--codec-auth](/cli/cmd-options#codec-auth) +::: -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +**--limit** _int_ -- [--color](/cli/cmd-options#color) +Maximum number of Workflow Executions to display. -- [--concurrency](/cli/cmd-options#concurrency) +**--page-size** _int_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Maximum number of Workflow Executions to fetch at a time from the server. -- [--depth](/cli/cmd-options#depth) +**--query**, **-q** _string_ -- [--env](/cli/cmd-options#env) +Content for an SQL-like `QUERY` List Filter. -- [--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. + +## metadata + +Issue a Query for and display user-set metadata like summary and +details for a specific Workflow Execution: + +``` +temporal workflow metadata \ + --workflow-id YourWorkflowId +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--reject-condition** _string-enum_ + +Optional flag for rejecting 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. + +## query + +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: + +``` +temporal workflow query \ + --workflow-id YourWorkflowId + --type YourQueryType + --input '{"YourInputKey": "YourInputValue"}' +``` + +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_ + +Query Type/Name. Required. + +**--reject-condition** _string-enum_ + +Optional flag for rejecting 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. + +## 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. + +## 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: + +``` +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. + +### describe + +Given a Workflow Execution and an Update ID, return information about its current status, including +a result if it has finished. + +``` +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. + +``` +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. + +``` +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`. + +``` +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. + +**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_ -The `temporal workflow update` command synchronously updates a running [Workflow Execution](/workflow-execution). +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") -Use the options listed below to change the command's behavior. +**--time-format** _string-enum_ -- [--address](/cli/cmd-options#address) +Time format. Accepted values: relative, iso, raw. (default "relative") -- [--codec-auth](/cli/cmd-options#codec-auth) +**--tls** _bool_ -- [--codec-endpoint](/cli/cmd-options#codec-endpoint) +Enable base TLS encryption. Does not have additional options like mTLS or client certs. -- [--color](/cli/cmd-options#color) +**--tls-ca-data** _string_ -- [--command-timeout](/cli/cmd-options#command-timeout) +Data for server CA certificate. Can't be used with --tls-ca-path. -- [--env](/cli/cmd-options#env) +**--tls-ca-path** _string_ -- [--first-execution-run-id](/cli/cmd-options#first-execution-run-id) +Path to server CA certificate. Can't be used with --tls-ca-data. -- [--grpc-meta](/cli/cmd-options#grpc-meta) +**--tls-cert-data** _string_ -- [--input](/cli/cmd-options#input) +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. -- [--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. diff --git a/sidebars.js b/sidebars.js index 6399625b8a..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", @@ -497,6 +498,7 @@ module.exports = { "cli/schedule", "cli/server", "cli/task-queue", + "cli/worker", "cli/workflow", ], },