diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index ee1a773a1..45366bfb6 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -1,72 +1,127 @@ name: Continuous Integration on: pull_request: - push: - branches: - - main - + workflow_dispatch: + release: + types: [published] jobs: - build-test: - strategy: - fail-fast: false - matrix: - os: [ubuntu-latest, macos-latest, macos-13, windows-latest, ubuntu-arm] - include: - - os: ubuntu-latest - checkGenCodeTarget: true - cloudTestTarget: true - - os: ubuntu-arm - runsOn: buildjet-4vcpu-ubuntu-2204-arm - runs-on: ${{ matrix.runsOn || matrix.os }} - env: - # We can't check this directly in the cloud test's `if:` condition below, - # so we have to check it here and report it in an env variable. - HAS_SECRETS: ${{ secrets.TEMPORAL_CLIENT_CERT != '' && secrets.TEMPORAL_CLIENT_KEY != '' }} + update: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + repository-projects: 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 repository uses: actions/checkout@v4 with: + path: cli submodules: recursive + persist-credentials: true + token: ${{ steps.generate_token.outputs.token }} - - name: Setup Go - uses: actions/setup-go@v5 + - name: Checkout docs repo + uses: actions/checkout@v4 with: - go-version-file: 'go.mod' - - - name: Install gotestsum - run: go install gotest.tools/gotestsum@latest + repository: temporalio/documentation + persist-credentials: true + token: ${{ steps.generate_token.outputs.token }} + path: docs - - name: Create junit-xml directory - run: mkdir junit-xml - - - name: Test - run: gotestsum --junitfile junit-xml/${{matrix.os}}.xml -- ./... - - - name: 'Upload junit-xml artifacts' - uses: actions/upload-artifact@v4 - if: always() + - name: Setup Go + uses: actions/setup-go@v4 with: - name: junit-xml--${{github.run_id}}--${{github.run_attempt}}--${{matrix.os}} - path: junit-xml - retention-days: 14 + go-version: '1.22' - - name: Regen code, confirm unchanged - if: ${{ matrix.checkGenCodeTarget }} + - name: Generate CLI docs run: | - go run ./temporalcli/internal/cmd/gen-commands - git diff --exit-code + cd cli/temporalcli/internal/cmd/gen-docs + go run . - - name: Test cloud - if: ${{ matrix.cloudTestTarget && env.HAS_SECRETS == 'true' }} + - name: Publish generated docs to cli repo env: - TEMPORAL_ADDRESS: ${{ vars.TEMPORAL_CLIENT_NAMESPACE }}.tmprl.cloud:7233 - TEMPORAL_NAMESPACE: ${{ vars.TEMPORAL_CLIENT_NAMESPACE }} - TEMPORAL_TLS_CERT: client.crt - TEMPORAL_TLS_CERT_CONTENT: ${{ secrets.TEMPORAL_CLIENT_CERT }} - TEMPORAL_TLS_KEY: client.key - TEMPORAL_TLS_KEY_CONTENT: ${{ secrets.TEMPORAL_CLIENT_KEY }} - shell: bash + GH_TOKEN: ${{ steps.generate_token.outputs.token }} + run: | + set -e + set -x + + if [ -z "$GH_TOKEN" ]; then + echo "GH_TOKEN is NOT set" + exit 1 + else + echo "GH_TOKEN is set" + fi + + + curl -H "Authorization: token ${{ steps.generate_token.outputs.token }}" https://api.github.com/user + + BRANCH_NAME="cli-update-docs-${{ github.ref_name }}" + # Remove the "/merge" suffix if it exists + BRANCH_NAME=${BRANCH_NAME%/merge} + + cd cli + + # Setup the committers identity. + git config --global user.email "sdk@temporal.io" + git config --global user.name "Temporal CLI" + + git checkout -b $BRANCH_NAME + git add . + # TODO: mention CLI release version + git commit -m "CLI docs update, autogenerated on CLI release $LATEST_TAG, ${{ github.ref_name }}" + git push origin "$BRANCH_NAME" + + gh pr create \ + --body "Autogenerated PR from https://github.com/temporalio/cli" \ + --title "CLI docs update $LATEST_TAG" \ + --head "$BRANCH_NAME" \ + --base "main" + + - name: Publish generated docs to documentation repo + env: + GH_TOKEN: ${{ steps.generate_token.outputs.token }} run: | - printf '%s\n' "$TEMPORAL_TLS_CERT_CONTENT" >> client.crt - printf '%s\n' "$TEMPORAL_TLS_KEY_CONTENT" >> client.key - go run ./cmd/temporal workflow list --limit 2 + set -e + set -x + + if [ -z "$GH_TOKEN" ]; then + echo "GH_TOKEN is NOT set" + exit 1 + else + echo "GH_TOKEN is set" + fi + + curl -H "Authorization: token ${{ steps.generate_token.outputs.token }}" https://api.github.com/user + + BRANCH_NAME="cli-update-docs-${{ github.ref_name }}" + # Remove the "/merge" suffix if it exists + BRANCH_NAME=${BRANCH_NAME%/merge} + + cd docs + + # Setup the committers identity. + git config --global user.email "sdk@temporal.io" + git config --global user.name "Temporal CLI" + + git checkout -b $BRANCH_NAME + cp ../cli/temporalcli/docs/*.mdx docs/cli/ + git add . + # TODO: mention CLI release version + git commit -m "CLI docs update, autogenerated on CLI release $LATEST_TAG, ${{ github.ref_name }}" + git push origin "$BRANCH_NAME" + + gh pr create \ + --body "Autogenerated PR from https://github.com/temporalio/cli" \ + --title "CLI docs update $LATEST_TAG" \ + --head "$BRANCH_NAME" \ + --base "main" diff --git a/temporalcli/docs/activity.mdx b/temporalcli/docs/activity.mdx new file mode 100644 index 000000000..aa376e76c --- /dev/null +++ b/temporalcli/docs/activity.mdx @@ -0,0 +1,961 @@ +--- +id: activity +title: temporal activity +sidebar_label: temporal activity +description: Learn how to use Temporal Activity commands for completing or failing Activity Executions in your Workflow. Optimize your Temporal Workflow management effectively. +toc_max_heading_level: 4 +keywords: + - activity + - activity complete + - activity update-options + - activity pause + - activity unpause + - activity reset + - activity execution + - activity fail + - cli reference + - cli-feature + - command-line-interface-cli + - temporal cli +tags: + - activity + - activity-complete + - activity-update-options + - activity-pause + - activity-unpause + - activity-reset + - activity-execution + - activity-fail + - cli-reference + - cli-feature + - command-line-interface-cli + - temporal-cli +--- + +## complete + +Complete an Activity, marking it as successfully finished. Specify the +Activity ID and include a JSON result for the returned value: + +``` +temporal activity complete \ + --activity-id YourActivityId \ + --workflow-id YourWorkflowId \ + --result '{"YourResultKey": "YourResultVal"}' +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--activity-id** _string_ + +Activity ID to complete. Required. + +**--identity** _string_ + +Identity of the user submitting this request. + +**--result** _string_ + +Result `JSON` to return. Required. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--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. + +## fail + +Fail an Activity, marking it as having encountered an error. Specify the +Activity and Workflow IDs: + +``` +temporal activity fail \ + --activity-id YourActivityId \ + --workflow-id YourWorkflowId +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--activity-id** _string_ + +Activity ID to fail. Required. + +**--detail** _string_ + +Reason for failing the Activity (JSON). + +**--identity** _string_ + +Identity of the user submitting this request. + +**--reason** _string_ + +Reason for failing the Activity. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--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. + +## pause + +Pause an Activity. + +If the Activity is not currently running (e.g. because it previously +failed), it will not be run again until it is unpaused. + +However, if the Activity is currently running, it will run to completion. +If the Activity is on its last retry attempt and fails, the failure will +be returned to the caller, just as if the Activity had not been paused. + +Activities can be specified by their Activity ID or Activity Type. +One of those parameters must be provided. If both are provided - Activity +Type will be used, and Activity ID will be ignored. + +``` + +Specify the Activity and Workflow IDs: + +``` +temporal activity pause \ + --activity-id YourActivityId \ + --workflow-id YourWorkflowId +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--activity-id**, **-a** _string_ + +Activity ID to pause. + +**--activity-type**, **-g** _string_ + +Activity Type to pause. + +**--identity** _string_ + +Identity of the user submitting this request. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--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 + +Re-schedule a previously-paused Activity for execution. + +If the Activity is not running and is past its retry timeout, it will be +scheduled immediately. Otherwise, it will be scheduled after its retry +timeout expires. + +Use `--reset-attempts` to reset the number of previous run attempts to +zero. For example, if an Activity is near the maximum number of attempts +N specified in its retry policy, `--reset-attempts` will allow the +Activity to be retried another N times after unpausing. + +Use `--reset-heartbeat` to reset the Activity's heartbeats. + +Activities can be specified by their Activity ID or Activity Type. +One of those parameters must be provided. 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 YourReasonForTermination +``` + + +Specify the Activity ID or Type and Workflow IDs: + +``` +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_ + +Override target TLS server name. + diff --git a/temporalcli/docs/batch.mdx b/temporalcli/docs/batch.mdx new file mode 100644 index 000000000..6d31a1363 --- /dev/null +++ b/temporalcli/docs/batch.mdx @@ -0,0 +1,392 @@ +--- +id: batch +title: temporal batch +sidebar_label: temporal batch +description: Use Temporal CLI to manage multiple Workflow Executions with Batch Jobs that can Cancel, Signal, or Terminate Workflows. Filter and monitor Batch Jobs effectively. +toc_max_heading_level: 4 +keywords: + - batch + - batch describe + - batch list + - batch terminate + - cli reference + - cli-feature + - command-line-interface-cli + - temporal cli +tags: + - batch + - batch-describe + - batch-list + - batch-terminate + - cli-reference + - cli-feature + - command-line-interface-cli + - temporal-cli +--- + +## describe + +Show the progress of an ongoing batch job. Pass a valid job ID to display its +information: + +``` +temporal batch describe \ + --job-id YourJobId +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--job-id** _string_ + +Batch job 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. + +## list + +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 YourNamespace +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--limit** _int_ + +Maximum number of batch jobs to display. + +**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 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 YourJobId \ + --reason YourTerminationReason +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--job-id** _string_ + +Job ID to terminate. Required. + +**--reason** _string_ + +Reason for terminating the batch job. Required. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--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/temporalcli/docs/env.mdx b/temporalcli/docs/env.mdx new file mode 100644 index 000000000..3b7daf142 --- /dev/null +++ b/temporalcli/docs/env.mdx @@ -0,0 +1,532 @@ +--- +id: env +title: temporal env +sidebar_label: temporal env +description: Temporal CLI 'env' commands allow the configuration, setting, deleting, and listing of environmental properties, making it easy to manage Temporal Server instances. +toc_max_heading_level: 4 +keywords: + - cli reference + - command-line-interface-cli + - configuration + - env + - env delete + - env get + - env list + - env set + - environment + - temporal cli +tags: + - cli-reference + - command-line-interface-cli + - configuration + - env + - env-delete + - env-get + - env-list + - env-set + - environment + - temporal-cli +--- + +## 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_ + +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 + +List the properties for a given environment: + +``` +temporal env get \ + --env YourEnvironment +``` + +Print a single property: + +``` +temporal env get \ + --env YourEnvironment \ + --key YourPropertyKey +``` + +If you don't specify an environment (with `--env` or by setting the +`TEMPORAL_ENV` variable), this command lists properties of the "default" +environment. + +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_ + +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 the environments you have set up on your local computer. Environments are +stored in "$HOME/.config/temporalio/temporal.yaml". + +Use the following options to change the behavior of this command. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +## set + +Assign a value to a property key and store it to an environment: + +``` +temporal env set \ + --env environment \ + --key property \ + --value value +``` + +If you don't specify an environment (with `--env` or by setting the +`TEMPORAL_ENV` variable), this command sets properties in the "default" +environment. + +Storing keys with CLI option names lets the CLI automatically set those +options for you. This reduces effort and helps avoid typos when issuing +commands. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--key**, **-k** _string_ + +Property name (required). + +**--value**, **-v** _string_ + +Property value (required). + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--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/temporalcli/docs/operator.mdx b/temporalcli/docs/operator.mdx new file mode 100644 index 000000000..93c9d6a54 --- /dev/null +++ b/temporalcli/docs/operator.mdx @@ -0,0 +1,2619 @@ +--- +id: operator +title: temporal operator +sidebar_label: temporal operator +description: Operator commands in Temporal allow actions on Namespaces, Search Attributes, Clusters and Nexus Endpoints using specific subcommands. Execute with "temporal operator [command] [subcommand] [options]". +toc_max_heading_level: 4 +keywords: + - cli reference + - cluster + - cluster health + - cluster list + - cluster remove + - cluster upsert + - command-line-interface-cli + - describe + - namespace + - namespace create + - namespace delete + - namespace describe + - namespace list + - nexus + - nexus endpoint + - nexus endpoint create + - nexus endpoint delete + - nexus endpoint get + - nexus endpoint list + - nexus endpoint update + - operator + - search attribute + - search attribute create + - search attribute list + - search attribute remove + - system + - temporal cli + - update +tags: + - cli-reference + - cluster + - cluster-health + - cluster-list + - cluster-remove + - cluster-upsert + - command-line-interface-cli + - describe + - namespace + - namespace-create + - namespace-delete + - namespace-describe + - namespace-list + - nexus + - nexus-endpoint + - nexus-endpoint-create + - nexus-endpoint-delete + - nexus-endpoint-get + - nexus-endpoint-list + - nexus-endpoint-update + - operator + - search-attribute + - search-attribute-create + - search-attribute-list + - search-attribute-remove + - system + - temporal-cli + - update +--- + +## cluster + +Perform operator actions on Temporal Services (also known as Clusters). + +``` +temporal operator cluster [subcommand] [options] +``` + +For example to check Service/Cluster health: + +``` +temporal operator cluster health +``` + +### describe + +View information about a Temporal Cluster (Service), including Cluster Name, +persistence store, and visibility store. Add `--detail` for additional info: + +``` +temporal operator cluster describe [--detail] +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--detail** _bool_ + +Show history shard count and Cluster/Service version information. + +**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. + +### health + +View information about the health of a Temporal Service: + +``` +temporal operator cluster health +``` + +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. + +### list + +Print a list of remote Temporal Clusters (Services) registered to the local +Service. Report details include the Cluster's name, ID, address, History Shard +count, Failover version, and availability: + +``` +temporal operator cluster list [--limit max-count] +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--limit** _int_ + +Maximum number of Clusters to display. + +**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 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. + +**Flags:** + +**--name** _string_ + +Cluster/Service 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. + +### system + +Show Temporal Server information for Temporal Clusters (Service): Server +version, scheduling support, and more. This information helps diagnose +problems with the Temporal Server. + +The command defaults to the local Service. Otherwise, use the +`--frontend-address` option to specify a Cluster (Service) endpoint: + +``` +temporal operator cluster system \ + --frontend-address "YourRemoteEndpoint:YourRemotePort" +``` + +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. + +### upsert + +Add, remove, or update a registered ("remote") Temporal Cluster (Service). + +``` +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. + +**Flags:** + +**--enable-connection** _bool_ + +Set the connection to "enabled". + +**--frontend-address** _string_ + +Remote endpoint. 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. + +## namespace + +Manage Temporal Cluster (Service) Namespaces: + +``` +temporal operator namespace [command] [command options] +``` + +For example: + +``` +temporal operator namespace create \ + --namespace YourNewNamespaceName +``` + +### create + +Create a new Namespace on the Temporal Service: + +``` +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. + +**Flags:** + +**--active-cluster** _string_ + +Active Cluster (Service) name. + +**--cluster** _string[]_ + +Cluster (Service) names for Namespace creation. Can be passed multiple times. + +**--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. + +**--global** _bool_ + +Enable multi-region data replication. + +**--history-archival-state** _string-enum_ + +History archival state. Accepted values: disabled, enabled. (default "disabled") + +**--history-uri** _string_ + +Archive history to this `URI`. Once enabled, can't be changed. + +**--retention** _duration_ + +Time to preserve closed Workflows before deletion. (default "72h") + +**--visibility-archival-state** _string-enum_ + +Visibility archival state. Accepted values: disabled, enabled. (default "disabled") + +**--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. + +### delete + +Removes a Namespace from the Service. + +``` +temporal operator namespace delete [options] +``` + +For example: + +``` +temporal operator namespace delete \ + --namespace YourNamespaceName +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--yes**, **-y** _bool_ + +Request confirmation before deletion. + +**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 + +Provide long-form information about a Namespace identified by its ID or name: + +``` +temporal operator namespace describe \ + --namespace-id YourNamespaceId +``` + +or + +``` +temporal operator namespace describe \ + --namespace YourNamespaceName +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--namespace-id** _string_ + +Namespace 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. + +### list + +Display a detailed listing for all Namespaces on the Service: + +``` +temporal operator namespace 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 a Namespace using properties you specify. + +``` +temporal operator namespace update [options] +``` + +Assign a Namespace's active Cluster (Service): + +``` +temporal operator namespace update \ + --namespace YourNamespaceName \ + --active-cluster NewActiveCluster +``` + +Promote a Namespace for multi-region data replication: + +``` +temporal operator namespace update \ + --namespace YourNamespaceName \ + --promote-global +``` + +You may update archives that were previously enabled or disabled. Note: URI +values for archival states can't be changed once enabled. + +``` +temporal operator namespace update \ + --namespace YourNamespaceName \ + --history-archival-state enabled \ + --visibility-archival-state disabled +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--active-cluster** _string_ + +Active Cluster (Service) name. + +**--cluster** _string[]_ + +Cluster (Service) names. + +**--data** _string[]_ + +Namespace data as `KEY=VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--description** _string_ + +Namespace description. + +**--email** _string_ + +Owner email. + +**--history-archival-state** _string-enum_ + +History archival state. Accepted values: disabled, enabled. + +**--history-uri** _string_ + +Archive history to this `URI`. Once enabled, can't be changed. + +**--promote-global** _bool_ + +Enable multi-region data replication. + +**--retention** _duration_ + +Length of time a closed Workflow is preserved before deletion. + +**--visibility-archival-state** _string-enum_ + +Visibility archival state. Accepted values: disabled, enabled. + +**--visibility-uri** _string_ + +Archive visibility data to this `URI`. Once enabled, can't be changed. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +## nexus + +These commands manage Nexus resources. + +Nexus commands follow this syntax: + +``` +temporal operator nexus [command] [subcommand] [options] +``` + +### endpoint + +These commands manage Nexus Endpoints. + +Nexus Endpoint commands follow this syntax: + +``` +temporal operator nexus endpoint [command] [options] +``` + +#### create + +Create a Nexus Endpoint on the Server. + +A Nexus Endpoint name is used in Workflow code to invoke Nexus Operations. +The endpoint target may either be a Worker, in which case +`--target-namespace` and `--target-task-queue` must both be provided, or +an external URL, in which case `--target-url` must be provided. + +This command will fail if an Endpoint with the same name is already +registered. + +``` +temporal operator nexus endpoint create \ + --name your-endpoint \ + --target-namespace your-namespace \ + --target-task-queue your-task-queue \ + --description-file DESCRIPTION.md +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--description** _string_ + +Nexus Endpoint description. You may use Markdown formatting in the Nexus Endpoint description. + +**--description-file** _string_ + +Path to the Nexus Endpoint description file. The contents of the description file may use Markdown formatting. + +**--name** _string_ + +Endpoint name. Required. + +**--target-namespace** _string_ + +Namespace where a handler Worker polls for Nexus tasks. + +**--target-task-queue** _string_ + +Task Queue that a handler Worker polls for Nexus tasks. + +**--target-url** _string_ + +An external Nexus Endpoint that receives forwarded Nexus requests. May be used as an alternative to `--target-namespace` and `--target-task-queue`. + +:::note + +Option is experimental. + +::: + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +#### delete + +Delete a Nexus Endpoint from the Server. + +``` +temporal operator nexus endpoint delete --name your-endpoint +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--name** _string_ + +Endpoint name. Required. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +#### get + +Get a Nexus Endpoint by name from the Server. + +``` +temporal operator nexus endpoint get --name your-endpoint +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--name** _string_ + +Endpoint name. Required. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +#### list + +List all Nexus Endpoints on the Server. + +``` +temporal operator nexus endpoint list +``` + +Use the following options to change the behavior of this command. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +#### update + +Update an existing Nexus Endpoint on the Server. + +A Nexus Endpoint name is used in Workflow code to invoke Nexus Operations. +The Endpoint target may either be a Worker, in which case +`--target-namespace` and `--target-task-queue` must both be provided, or +an external URL, in which case `--target-url` must be provided. + +The Endpoint is patched; existing fields for which flags are not provided +are left as they were. + +Update only the target task queue: + +``` +temporal operator nexus endpoint update \ + --name your-endpoint \ + --target-task-queue your-other-queue +``` + +Update only the description: + +``` +temporal operator nexus endpoint update \ + --name your-endpoint \ + --description-file DESCRIPTION.md +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--description** _string_ + +Nexus Endpoint description. You may use Markdown formatting in the Nexus Endpoint description. + +**--description-file** _string_ + +Path to the Nexus Endpoint description file. The contents of the description file may use Markdown formatting. + +**--name** _string_ + +Endpoint name. Required. + +**--target-namespace** _string_ + +Namespace where a handler Worker polls for Nexus tasks. + +**--target-task-queue** _string_ + +Task Queue that a handler Worker polls for Nexus tasks. + +**--target-url** _string_ + +An external Nexus Endpoint that receives forwarded Nexus requests. May be used as an alternative to `--target-namespace` and `--target-task-queue`. + +:::note + +Option is experimental. + +::: + +**--unset-description** _bool_ + +Unset the description. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +## search-attribute + +Create, list, or remove Search Attributes fields stored in a Workflow +Execution's metadata: + +``` +temporal operator search-attribute create \ + --name YourAttributeName \ + --type Keyword +``` + +Supported types include: Text, Keyword, Int, Double, Bool, Datetime, and +KeywordList. + +If you wish to delete a Search Attribute, please contact support +at https://support.temporal.io. + +### create + +Add one or more custom Search Attributes: + +``` +temporal operator search-attribute create \ + --name YourAttributeName \ + --type Keyword +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--name** _string[]_ + +Search Attribute name. Required. + +**--type** _string-enum[]_ + +Search Attribute type. Required. Accepted values: Text, Keyword, Int, Double, Bool, Datetime, KeywordList. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +### list + +Display a list of active Search Attributes that can be assigned or used with +Workflow Queries. You can manage this list and add attributes as needed: + +``` +temporal operator search-attribute list +``` + +Use the following options to change the behavior of this command. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +### remove + +Remove custom Search Attributes from the options that can be assigned or used +with Workflow Queries. + +``` +temporal operator search-attribute remove \ + --name YourAttributeName +``` + +Remove attributes without confirmation: + +``` +temporal operator search-attribute remove \ + --name YourAttributeName \ + --yes +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--name** _string[]_ + +Search Attribute name. Required. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm removal. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +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/temporalcli/docs/schedule.mdx b/temporalcli/docs/schedule.mdx new file mode 100644 index 000000000..83c6f340b --- /dev/null +++ b/temporalcli/docs/schedule.mdx @@ -0,0 +1,1343 @@ +--- +id: schedule +title: temporal schedule +sidebar_label: temporal schedule +description: Temporal's Schedule commands allow users to create, update, and manage Workflow Executions seamlessly for automation, supporting commands for creation, backfill, deletion, and more. +toc_max_heading_level: 4 +keywords: + - backfill + - cli reference + - command-line-interface-cli + - schedule + - schedule backfill + - schedule create + - schedule delete + - schedule describe + - schedule list + - schedule toggle + - schedule trigger + - schedule update + - temporal cli + - updates +tags: + - backfill + - cli-reference + - command-line-interface-cli + - schedule + - schedule-backfill + - schedule-create + - schedule-delete + - schedule-describe + - schedule-list + - schedule-toggle + - schedule-trigger + - schedule-update + - temporal-cli + - updates +--- + +## backfill + +Batch-execute actions that would have run during a specified time interval. +Use this command to fill in Workflow runs from when a Schedule was paused, +before a Schedule was created, from the future, or to re-process a previously +executed interval. + +Backfills require a Schedule ID and the time period covered by the request. +It's best to use the `BufferAll` or `AllowAll` policies to avoid conflicts +and ensure no Workflow Executions are skipped. + +For example: + +``` +temporal schedule backfill \ + --schedule-id "YourScheduleId" \ + --start-time "2022-05-01T00:00:00Z" \ + --end-time "2022-05-31T23:59:59Z" \ + --overlap-policy BufferAll +``` + +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_ + +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. + +## create + +Create a new Schedule on the Temporal Service. A Schedule automatically starts +new Workflow Executions at the times you specify. + +For example: + +``` + temporal schedule create \ + --schedule-id "YourScheduleId" \ + --calendar '{"dayOfWeek":"Fri","hour":"3","minute":"30"}' \ + --workflow-id YourBaseWorkflowIdName \ + --task-queue YourTaskQueue \ + --type YourWorkflowType +``` + +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 delete \ + --schedule-id YourScheduleId +``` + +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") + +**--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 describe \ + --schedule-id YourScheduleId +``` + +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") + +**--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 + +Lists the Schedules hosted by a Namespace: + +``` +temporal schedule list \ + --namespace YourNamespace +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--long**, **-l** _bool_ + +Show detailed information. + +**--query**, **-q** _string_ + +Filter results using given List Filter. + +**--really-long** _bool_ + +Show extensive information in non-table form. + +**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. + +## toggle + +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_ + +Schedule ID. Required. + +**--unpause** _bool_ + +Unpause the Schedule. + +**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. + +## trigger + +Trigger a Schedule to run immediately: + +``` +temporal schedule trigger \ + --schedule-id "YourScheduleId" +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--overlap-policy** _string-enum_ + +Policy for handling overlapping Workflow Executions. Accepted values: Skip, BufferOne, BufferAll, CancelOther, TerminateOther, AllowAll. (default "Skip") + +**--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") + +**--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 "YourScheduleId" \ + --workflow-type "NewWorkflowType" +``` + +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. + diff --git a/temporalcli/docs/server.mdx b/temporalcli/docs/server.mdx new file mode 100644 index 000000000..9a2b9e877 --- /dev/null +++ b/temporalcli/docs/server.mdx @@ -0,0 +1,230 @@ +--- +id: server +title: temporal server +sidebar_label: temporal server +description: Manage your Temporal Server easily with CLI commands. Start a local server using `temporal server start-dev` and access the Web UI at http://localhost:8233. Customize with multiple options. +toc_max_heading_level: 4 +keywords: + - cli reference + - command-line-interface-cli + - server + - server start-dev + - temporal cli +tags: + - cli-reference + - command-line-interface-cli + - server + - server-start-dev + - temporal-cli +--- + +## start-dev + +Run a development Temporal Server on your local system. + ++------------------------------------------------------------------------+ +| WARNING: The development server is not intended for production use. | +| It skips certain HTTP security checks to make local use simpler. | +| | +| For production use, see: | +| https://docs.temporal.io/production-deployment | ++------------------------------------------------------------------------+ + +View the Web UI for the default configuration at: http://localhost:8233 + +``` +temporal server start-dev +``` + +Add persistence for Workflow Executions across runs: + +``` +temporal server start-dev \ + --db-filename path-to-your-local-persistent-store +``` + +Set the port from the front-end gRPC Service (7233 default): + +``` +temporal server start-dev \ + --port 7000 +``` + +Use a custom port for the Web UI. The default is the gRPC port (7233 default) +plus 1000 (8233): + +``` +temporal server start-dev \ + --ui-port 3000 +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--db-filename**, **-f** _string_ + +Path to file for persistent Temporal state store. By default, Workflow Executions are lost when the server process dies. + +**--dynamic-config-value** _string[]_ + +Dynamic configuration value using `KEY=VALUE` pairs. Keys must be identifiers, and values must be JSON values. For example: 'YourKey="YourString"'. Can be passed multiple times. + +**--headless** _bool_ + +Disable the Web UI. + +**--http-port** _int_ + +Port for the HTTP API service. Defaults to a random free port. (default "0") + +**--ip** _string_ + +IP address bound to the front-end Service. (default "localhost") + +**--log-config** _bool_ + +Log the server config to stderr. + +**--metrics-port** _int_ + +Port for '/metrics'. Default is off. + +**--namespace**, **-n** _string[]_ + +Namespaces to be created at launch. The "default" Namespace is always created automatically. + +**--port**, **-p** _int_ + +Port for the front-end gRPC Service. (default "7233") + +**--search-attribute** _string[]_ + +Search attributes to register using `KEY=VALUE` pairs. Keys must be identifiers, and values must be the search attribute type, which is one of the following: Text, Keyword, Int, Double, Bool, Datetime, KeywordList. + +**--sqlite-pragma** _string[]_ + +SQLite pragma statements in "PRAGMA=VALUE" format. + +**--ui-asset-path** _string_ + +UI custom assets path. + +**--ui-codec-endpoint** _string_ + +UI remote codec HTTP endpoint. + +**--ui-ip** _string_ + +IP address bound to the Web UI. Default is same as '--ip' value. + +**--ui-port** _int_ + +Port for the Web UI. Default is '--port' value + 1000. + +**--ui-public-path** _string_ + +The public base path for the Web UI. Default is `/`. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--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/temporalcli/docs/task-queue.mdx b/temporalcli/docs/task-queue.mdx new file mode 100644 index 000000000..8a26097c0 --- /dev/null +++ b/temporalcli/docs/task-queue.mdx @@ -0,0 +1,2325 @@ +--- +id: task-queue +title: temporal task-queue +sidebar_label: temporal task-queue +description: Temporal Task Queue commands facilitate operations like describing poller info, displaying partitions, fetching compatible Build IDs, and determining Build ID reachability for effective Workflow and Activity management. +toc_max_heading_level: 4 +keywords: + - cli reference + - command-line-interface-cli + - list partitions + - task queue + - task queue describe + - temporal cli +tags: + - cli-reference + - command-line-interface-cli + - list-partitions + - task-queue + - task-queue-describe + - temporal-cli +--- + +## describe + +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_ + +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-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. + +**Flags:** + +**--build-id** _string[]_ + +One or more Build ID strings. Can be passed multiple times. + +**--reachability-type** _string-enum_ + +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") + +**--task-queue**, **-t** _string[]_ + +Search only the specified task queue(s). Can be passed multiple times. + +**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-build-ids + ++-----------------------------------------------------------------------------+ +| 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: + +``` +temporal task-queue get-build-ids \ + --task-queue YourTaskQueue +``` + +This command is limited to Namespaces that support Worker versioning. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--max-sets** _int_ + +Max return count. Use 1 for default major version. Use 0 for all sets. (default "0") + +**--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. + +## list-partition + +Display a Task Queue's partition list with assigned matching nodes: + +``` +temporal task-queue list-partition \ + --task-queue YourTaskQueue +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--task-queue**, **-t** _string_ + +Task Queue name. Required. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +## update-build-ids + ++-----------------------------------------------------------------------------+ +| 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/temporalcli/docs/worker.mdx b/temporalcli/docs/worker.mdx new file mode 100644 index 000000000..59777d8a5 --- /dev/null +++ b/temporalcli/docs/worker.mdx @@ -0,0 +1,1217 @@ +--- +id: worker +title: temporal worker +sidebar_label: temporal worker +description: Learn how to read or modify state associated with a Worker, such as Worker Deployments. +toc_max_heading_level: 4 +keywords: + - worker + - worker deployment +tags: + - worker + - worker-deployment +--- + +## deployment + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Deployment commands perform operations on Worker Deployments: + +``` +temporal worker deployment [command] [options] +``` + +For example: + +``` +temporal worker deployment list +``` + +Lists the Deployments in the client's namespace. + +Arguments can be Worker Deployment Versions associated with +a Deployment, using a fully qualified Version identifier that +concatenates the Deployment Name and the Build ID with the +reserved separator ".". + +For example: + +``` +temporal worker deployment set-current-version \ + --version YourDeploymentName.YourBuildID +``` + +Sets the current Deployment Version for a given Deployment. + +### delete + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Remove a Worker Deployment given its Deployment Name. +A Deployment can only be deleted if it has no Version in it. + +``` +temporal worker deployment delete [options] +``` + +For example, setting the user identity that removed the deployment: + +``` +temporal worker deployment delete \ + --name YourDeploymentName \ + --identity YourIdentity + +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--identity** _string_ + +Identity of the user submitting this request. + +**--name**, **-d** _string_ + +Name for a Worker Deployment. Required. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +### delete-version + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Remove a Worker Deployment Version given its fully-qualified identifier. +This is rarely needed during normal operation +since unused Versions are eventually garbage collected. +The client can delete a Version only when all of the following conditions +are met: + - It is not the Current or Ramping Version for this Deployment. + - It has no active pollers, i.e., none of the task queues in the + Version have pollers. + - It is not draining. This requirement can be ignored with the option +`--skip-drainage`. + +``` +temporal worker deployment delete-version [options] +``` + +For example, skipping the drainage restriction: + +``` +temporal worker deployment delete-version \ + --version YourDeploymentName.YourBuildID \ + --skip-drainage +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--identity** _string_ + +Identity of the user submitting this request. + +**--skip-drainage** _bool_ + +Ignore the deletion requirement of not draining. + +**--version**, **-v** _string_ + +Fully-qualified name for a Worker Deployment Version. Use the format `YourDeploymentName.YourBuildID`. Required. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +### describe + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Describe properties of a Worker Deployment, such as the versions +associated with it, routing information of new or existing tasks +executed by this deployment, or its creation time. + +``` +temporal worker deployment describe [options] +``` + +For example, to describe a deployment `YourDeploymentName` in the default +namespace: + +``` +temporal worker deployment describe \ + --name YourDeploymentName +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--name**, **-d** _string_ + +Name for a Worker Deployment. Required. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +### describe-version + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Describe properties of a Worker Deployment Version, such as the task +queues polled by workers in this Deployment Version, or drainage +information required to safely decommission workers, or user-provided +metadata, or its creation/modification time. + +``` +temporal worker deployment describe-version [options] +``` + +For example, to describe a deployment version in a deployment +`YourDeploymentName`, with Build ID `YourBuildID`, and in the default +namespace: + +``` +temporal worker deployment describe-version \ + --version YourDeploymentName.YourBuildID +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--version**, **-v** _string_ + +Fully-qualified name for a Worker Deployment Version. Use the format `YourDeploymentName.YourBuildID`. Required. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +### list + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +List existing Worker Deployments in the client's namespace. + +``` +temporal worker deployment list [options] +``` + +For example, listing Deployments in YourDeploymentNamespace: + +``` +temporal worker deployment list \ + --namespace YourDeploymentNamespace +``` + +Use the following options to change the behavior of this command. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +### set-current-version + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Set the Current Version for a Deployment. +When a Version is current, Workers of that Deployment Version will receive +tasks from new Workflows, and from existing AutoUpgrade Workflows that +are running on this Deployment. + +If not all the expected Task Queues are being polled by Workers in the +new Version the request will fail. To override this protection use +`--ignore-missing-task-queues`. Note that this would ignore task queues +in a deployment that are not yet discovered, leading to inconsistent task +queue configuration. + +``` +temporal worker deployment set-current-version [options] +``` + +For example, to set the Current Version of a deployment +`YourDeploymentName`, with a version with Build ID `YourBuildID`, and +in the default namespace: + +``` +temporal worker deployment set-current-version \ + --version YourDeploymentName.YourBuildID +``` + +The target of set-current-version can also be `__unversioned__`, which +moves tasks to unversioned workers, but in this case we also need to +specify the Deployment Name. + +``` +temporal worker deployment set-current-version \ + --version __unversioned__ \ + --deployment-name YourDeploymentName +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--deployment-name** _string_ + +Deployment name. Only needed when `--version` is `__unversioned__` or empty. + +**--identity** _string_ + +Identity of the user submitting this request. + +**--ignore-missing-task-queues** _bool_ + +Override protection to accidentally remove task queues. + +**--version**, **-v** _string_ + +Fully-qualified name for a Worker Deployment Version. Use the format `YourDeploymentName.YourBuildID`. Required. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm set Current Version. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +### set-ramping-version + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ + +Set the Ramping Version and Percentage for a Deployment. + +The Ramping Version can be set to a fully-qualified Version of the form +`YourDeploymentName.YourBuildID`, or set to "__unversioned__", a special +value that represents all the unversioned workers. + +The Ramping Percentage is a float with values in the range [0, 100]. +A value of 100 does not make the Ramping Version Current, use +`set-current-version` instead. + +To remove a Ramping Version use the flag `--delete`. + +If not all the expected Task Queues are being polled by Workers in the +new Ramping Version the request will fail. To override this protection use +`--ignore-missing-task-queues`. Note that this would ignore task queues +in a deployment that are not yet discovered, leading to inconsistent task +queue configuration. + +``` +temporal worker deployment set-ramping-version [options] +``` + +For example, to set the Ramping Version of a deployment +`YourDeploymentName`, with a version with Build ID `YourBuildID`, with +10 percent of tasks redirected to this version, and +using the default namespace: + +``` +temporal worker deployment set-ramping-version \ + --version YourDeploymentName.YourBuildID + --percentage 10.0 +``` + +And to remove that ramping: + +``` +temporal worker deployment set-ramping-version \ + --version YourDeploymentName.YourBuildID \ + --delete +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--delete** _bool_ + +Delete the Ramping Version. + +**--deployment-name** _string_ + +Deployment name. Only needed when `--version` is `__unversioned__`. + +**--identity** _string_ + +Identity of the user submitting this request. + +**--ignore-missing-task-queues** _bool_ + +Override protection to accidentally remove task queues. + +**--percentage** _float_ + +Percentage of tasks redirected to the Ramping Version. Valid range [0,100]. + +**--version**, **-v** _string_ + +Fully-qualified name for a Worker Deployment Version. Use the format `YourDeploymentName.YourBuildID`. Required. + +**--yes**, **-y** _bool_ + +Don't prompt to confirm set Ramping Version. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +### update-metadata-version + ++---------------------------------------------------------------------+ +| CAUTION: Worker Deployment is experimental. Deployment commands are | +| subject to change. | ++---------------------------------------------------------------------+ +Update metadata associated with a Worker Deployment Version. + +For example: + +``` + temporal worker deployment update-metadata-version \ + --version YourDeploymentName.YourBuildID \ + --metadata bar=1 \ + --metadata foo=true +``` + +The current metadata is also returned with `describe-version`: + +``` + temporal worker deployment describe-version \ + --version YourDeploymentName.YourBuildID \ +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--metadata** _string[]_ + +Set deployment metadata using `KEY="VALUE"` pairs. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--remove-entries** _string[]_ + +Keys of entries to be deleted from metadata. Can be passed multiple times. + +**--version**, **-v** _string_ + +Fully-qualified name for a Worker Deployment Version. Use the format `YourDeploymentName.YourBuildID`. Required. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + diff --git a/temporalcli/docs/workflow.mdx b/temporalcli/docs/workflow.mdx new file mode 100644 index 000000000..44423bcec --- /dev/null +++ b/temporalcli/docs/workflow.mdx @@ -0,0 +1,4119 @@ +--- +id: workflow +title: temporal workflow +sidebar_label: temporal workflow +description: Temporal Workflow commands enable operations on Workflow Executions, such as cancel, count, delete, describe, execute, list, update-options, query, reset, reset-batch, show, signal, stack, start, terminate, trace, and update, enhancing efficiency and control. +toc_max_heading_level: 4 +keywords: + - call stack + - cancellation + - child workflows + - cli reference + - command-line-interface-cli + - event history + - query + - resets-feature + - signals + - signals-feature + - stack trace + - temporal cli + - termination + - workflow + - workflow cancel + - workflow count + - workflow delete + - workflow describe + - workflow execute + - workflow execution + - workflow list + - workflow metadata + - workflow query + - workflow reset + - workflow reset-batch + - workflow show + - workflow signal + - workflow stack + - workflow start + - workflow terminate + - workflow trace + - workflow update-options +tags: + - call-stack + - cancellation + - child-workflows + - cli-reference + - command-line-interface-cli + - event-history + - query + - resets-feature + - signals + - signals-feature + - stack-trace + - temporal-cli + - termination + - workflow + - workflow-cancel + - workflow-count + - workflow-delete + - workflow-describe + - workflow-execute + - workflow-execution + - workflow-list + - workflow-metadata + - workflow-query + - workflow-reset + - workflow-reset-batch + - workflow-show + - workflow-signal + - workflow-stack + - workflow-start + - workflow-terminate + - workflow-trace + - workflow-update-options +--- + +## cancel + +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. + +Use the Workflow ID to cancel an Execution: + +``` +temporal workflow cancel \ + --workflow-id YourWorkflowId +``` + +A visibility Query lets you send bulk cancellations to Workflow Executions +matching the results: + +``` +temporal workflow cancel \ + --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. 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. + +## count + +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. + +**--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 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_ + +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 + +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. + +**--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 + +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: + +``` +temporal workflow execute + --workflow-id YourWorkflowId \ + --type YourWorkflow \ + --task-queue YourTaskQueue \ + --input '{"some-key": "some-value"}' +``` + +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. + +Use the following options to change the behavior of this command. + +**Flags:** + +**--cron** _string_ + +Cron schedule for the Workflow. Deprecated. Use Schedules instead. + +**--detailed** _bool_ + +Display events as sections instead of table. Does not apply to JSON output. + +**--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. + +## execute-update-with-start + +Send a message to a Workflow Execution to invoke an Update handler, and wait for +the update to complete. If the Workflow Execution is not running, then a new workflow +execution is started and the update is sent. + +Experimental. + +``` +temporal workflow execute-update-with-start \ + --update-name YourUpdate \ + --update-input '{"update-key": "update-value"}' \ + --workflow-id YourWorkflowId \ + --type YourWorkflowType \ + --task-queue YourTaskQueue \ + --id-conflict-policy Fail \ + --input '{"wf-key": "wf-value"}' +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--cron** _string_ + +Cron schedule for the Workflow. Deprecated. Use Schedules instead. + +**--execution-timeout** _duration_ + +Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks. + +**--fail-existing** _bool_ + +Fail if the Workflow already exists. + +**--id-conflict-policy** _string-enum_ + +Determines how to resolve a conflict when spawning a new Workflow Execution with a particular Workflow Id used by an existing Open Workflow Execution. Accepted values: Fail, UseExisting, TerminateExisting. + +**--id-reuse-policy** _string-enum_ + +Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning. + +**--input**, **-i** _string[]_ + +Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments. + +**--input-base64** _bool_ + +Assume inputs are base64-encoded and attempt to decode them. + +**--input-file** _string[]_ + +A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments. + +**--input-meta** _string[]_ + +Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. + +**--memo** _string[]_ + +Memo using 'KEY="VALUE"' pairs. Use JSON values. + +**--run-id**, **-r** _string_ + +Run ID. If unset, looks for an Update against the currently-running Workflow Execution. + +**--run-timeout** _duration_ + +Fail a Workflow Run if it lasts longer than `DURATION`. + +**--search-attribute** _string[]_ + +Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times. + +**--start-delay** _duration_ + +Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately. + +**--static-details** _string_ + +Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines. + +:::note + +Option is experimental. + +::: + +**--static-summary** _string_ + +Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line. + +:::note + +Option is experimental. + +::: + +**--task-queue**, **-t** _string_ + +Workflow Task queue. Required. + +**--task-timeout** _duration_ + +Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s") + +**--type** _string_ + +Workflow Type name. Required. + +**--update-first-execution-run-id** _string_ + +Parent Run ID. The update is sent to the last Workflow Execution in the chain started with this Run ID. + +**--update-id** _string_ + +Update ID. If unset, defaults to a UUID. + +**--update-input** _string[]_ + +Update input value. Use JSON content or set --update-input-meta to override. Can't be combined with --update-input-file. Can be passed multiple times to pass multiple arguments. + +**--update-input-base64** _bool_ + +Assume update inputs are base64-encoded and attempt to decode them. + +**--update-input-file** _string[]_ + +A path or paths for input file(s). Use JSON content or set --update-input-meta to override. Can't be combined with --update-input. Can be passed multiple times to pass multiple arguments. + +**--update-input-meta** _string[]_ + +Input update payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. + +**--update-name** _string_ + +Update name. Required. + +**--workflow-id**, **-w** _string_ + +Workflow ID. If not supplied, the Service generates a unique ID. + +**Global Flags:** + +**--address** _string_ + +Temporal Service gRPC endpoint. (default "127.0.0.1:7233") + +**--api-key** _string_ + +API key for request. + +**--codec-auth** _string_ + +Authorization header for Codec Server requests. + +**--codec-endpoint** _string_ + +Remote Codec Server endpoint. + +**--codec-header** _string[]_ + +HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--color** _string-enum_ + +Output coloring. Accepted values: always, never, auto. (default "auto") + +**--command-timeout** _duration_ + +The command execution timeout. 0s means no timeout. + +**--env** _string_ + +Active environment name (`ENV`). (default "default") + +**--env-file** _string_ + +Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. + +**--grpc-meta** _string[]_ + +HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. + +**--log-format** _string-enum_ + +Log format. Accepted values: text, json. (default "text") + +**--log-level** _string-enum_ + +Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info") + +**--namespace**, **-n** _string_ + +Temporal Service Namespace. (default "default") + +**--no-json-shorthand-payloads** _bool_ + +Raw payload output, even if the JSON option was used. + +**--output**, **-o** _string-enum_ + +Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text") + +**--time-format** _string-enum_ + +Time format. Accepted values: relative, iso, raw. (default "relative") + +**--tls** _bool_ + +Enable base TLS encryption. Does not have additional options like mTLS or client certs. + +**--tls-ca-data** _string_ + +Data for server CA certificate. Can't be used with --tls-ca-path. + +**--tls-ca-path** _string_ + +Path to server CA certificate. Can't be used with --tls-ca-data. + +**--tls-cert-data** _string_ + +Data for x509 certificate. Can't be used with --tls-cert-path. + +**--tls-cert-path** _string_ + +Path to x509 certificate. Can't be used with --tls-cert-data. + +**--tls-disable-host-verification** _bool_ + +Disable TLS host-name verification. + +**--tls-key-data** _string_ + +Private certificate key data. Can't be used with --tls-key-path. + +**--tls-key-path** _string_ + +Path to x509 private key. Can't be used with --tls-key-data. + +**--tls-server-name** _string_ + +Override target TLS server name. + +## fix-history-json + +Reserialize an Event History JSON file: + +``` +temporal workflow fix-history-json \ + --source /path/to/original.json \ + --target /path/to/reserialized.json +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--source**, **-s** _string_ + +Path to the original file. Required. + +**--target**, **-t** _string_ + +Path to the results file. When omitted, output is sent to stdout. + +**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 Workflow Executions. The optional `--query` limits the output to +Workflows matching a Query: + +``` +temporal workflow list \ + --query YourQuery` +``` + +Visit https://docs.temporal.io/visibility to read more about Search Attributes +and Query creation. See `temporal batch --help` for a quick reference. + +View a list of archived Workflow Executions: + +``` +temporal workflow list \ + --archived +``` + +Use the following options to change the behavior of this command. + +**Flags:** + +**--archived** _bool_ + +Limit output to archived Workflow Executions. + +:::note + +Option is experimental. + +::: + +**--limit** _int_ + +Maximum number of Workflow Executions to display. + +**--page-size** _int_ + +Maximum number of Workflow Executions to fetch at a time from the server. + +**--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. + +**--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. + +## 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_ + +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. +