diff --git a/docs/cli/activity.mdx b/docs/cli/activity.mdx index 1512d372f5..7dd5b717a4 100644 --- a/docs/cli/activity.mdx +++ b/docs/cli/activity.mdx @@ -253,7 +253,7 @@ is provided - it will stay paused. Either `--activity-id` (with `--workflow-id`) or `--query` must be specified. -### Resetting activities that heartbeat {/* #reset-heartbeats */} +### Resetting activities that heartbeat {#reset-heartbeats} Activities that heartbeat will receive a [Canceled failure](/references/failures#cancelled-failure) the next time they heartbeat after a reset. diff --git a/docs/cli/nexus.mdx b/docs/cli/nexus.mdx new file mode 100644 index 0000000000..2faba9edd3 --- /dev/null +++ b/docs/cli/nexus.mdx @@ -0,0 +1,253 @@ +--- +id: nexus +title: Temporal CLI nexus command reference +sidebar_label: nexus +description: Learn how to use Temporal Nexus commands for starting, listing, and managing Nexus Operation Executions. +toc_max_heading_level: 4 +keywords: + - nexus + - nexus operation + - nexus operation start + - nexus operation execute + - nexus operation describe + - nexus operation cancel + - nexus operation terminate + - nexus operation list + - nexus operation count + - cli reference + - cli-feature + - command-line-interface-cli + - temporal cli +tags: + - Nexus + - Temporal CLI +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from https://github.com/temporalio/cli/blob/main/internal/commandsgen/commands.yml via internal/cmd/gen-docs */} + +This page provides a reference for the `temporal` CLI `nexus` command. The flags applicable to each subcommand are presented in a table within the heading for the subcommand. Refer to [Global Flags](#global-flags) for flags that you can use with every subcommand. + +## operation + +These commands manage Nexus Operation Executions. + +Nexus Operation commands follow this syntax: + +``` +temporal nexus operation [command] [options] +``` + +### cancel + +Request cancellation of a Nexus Operation. + +``` +temporal nexus operation cancel \ + --operation-id YourOperationId +``` + +The Operation handler determines how to handle the +cancellation request. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--operation-id` | Yes | **string** Nexus Operation ID. | +| `--reason` | No | **string** Reason for cancellation. | +| `--run-id`, `-r` | No | **string** Run ID of the Nexus Operation. | + +### count + +Return a count of Nexus Operations. Use `--query` +to filter the operations to be counted. + +``` +temporal nexus operation count \ + --query 'NexusEndpoint="YourEndpoint"' +``` + +Visit https://docs.temporal.io/visibility to read more about +Search Attributes and queries. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--query`, `-q` | No | **string** Query to filter Nexus Operation Executions to count. | + +### describe + +Display detailed information about a specific Nexus +Operation Execution. + +``` +temporal nexus operation describe \ + --operation-id YourOperationId +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--operation-id` | Yes | **string** Nexus Operation ID. | +| `--raw` | No | **bool** Print properties without changing their format. | +| `--run-id`, `-r` | No | **string** Run ID of the Nexus Operation. | + +### execute + +Start a new Nexus Operation Execution and block until +it completes. The result is output to stdout. + +``` +temporal nexus operation execute \ + --endpoint YourEndpoint \ + --service YourService \ + --operation YourOperation \ + --operation-id YourOperationId \ + --input '{"some-key": "some-value"}' +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--endpoint` | Yes | **string** Nexus Endpoint name. | +| `--id-conflict-policy` | No | **string-enum** Policy for handling an Operation ID conflict with a running operation. Accepted values: Fail, UseExisting, TerminateExisting. | +| `--id-reuse-policy` | No | **string-enum** Policy for re-using an Operation ID from a previously closed operation. Accepted values: AllowDuplicate, RejectDuplicate. | +| `--input`, `-i` | No | **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` | No | **bool** Assume inputs are base64-encoded and attempt to decode them. | +| `--input-file` | No | **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` | No | **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. Repeated metadata keys are applied to the corresponding inputs in the provided order. | +| `--operation` | Yes | **string** Nexus Operation name. | +| `--operation-id` | No | **string** Nexus Operation ID. If not supplied, a unique ID is generated. | +| `--schedule-to-close-timeout` | No | **duration** Total time the operation is allowed to run. | +| `--service` | Yes | **string** Nexus Service name. | + +### list + +List Nexus Operations. Use `--query` to filter results. + +``` +temporal nexus operation list \ + --query 'NexusEndpoint="YourEndpoint"' +``` + +Visit https://docs.temporal.io/visibility to read more about +Search Attributes and queries. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--limit` | No | **int** Maximum number of Nexus Operation Executions to display. | +| `--page-size` | No | **int** Maximum number of Nexus Operation Executions to fetch at a time from the server. | +| `--query`, `-q` | No | **string** Query to filter the Nexus Operation Executions to list. | + +### result + +Wait for a Nexus Operation to complete and output +the result. + +``` +temporal nexus operation result \ + --operation-id YourOperationId +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--operation-id` | Yes | **string** Nexus Operation ID. | +| `--run-id`, `-r` | No | **string** Run ID of the Nexus Operation. | + +### start + +Start a new Nexus Operation. Outputs the +Operation ID and Run ID. + +``` +temporal nexus operation start \ + --endpoint YourEndpoint \ + --service YourService \ + --operation YourOperation \ + --operation-id YourOperationId \ + --input '{"some-key": "some-value"}' +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--endpoint` | Yes | **string** Nexus Endpoint name. | +| `--id-conflict-policy` | No | **string-enum** Policy for handling an Operation ID conflict with a running operation. Accepted values: Fail, UseExisting, TerminateExisting. | +| `--id-reuse-policy` | No | **string-enum** Policy for re-using an Operation ID from a previously closed operation. Accepted values: AllowDuplicate, RejectDuplicate. | +| `--input`, `-i` | No | **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` | No | **bool** Assume inputs are base64-encoded and attempt to decode them. | +| `--input-file` | No | **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` | No | **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. Repeated metadata keys are applied to the corresponding inputs in the provided order. | +| `--operation` | Yes | **string** Nexus Operation name. | +| `--operation-id` | No | **string** Nexus Operation ID. If not supplied, a unique ID is generated. | +| `--schedule-to-close-timeout` | No | **duration** Total time the operation is allowed to run. | +| `--service` | Yes | **string** Nexus Service name. | + +### terminate + +Terminate a Nexus Operation. + +``` +temporal nexus operation terminate \ + --operation-id YourOperationId \ + --reason YourReason +``` + +Operation handlers cannot see or respond to terminations. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--operation-id` | Yes | **string** Nexus Operation ID. | +| `--reason` | No | **string** Reason for termination. Defaults to a message with the current user's name. | +| `--run-id`, `-r` | No | **string** Run ID of the Nexus Operation. | + +## Global Flags + +The following options can be used with any command. + +| Flag | Required | Description | Default | +|------|----------|-------------|--------| +| `--address` | No | **string** Temporal Service gRPC endpoint. | `localhost:7233` | +| `--api-key` | No | **string** API key for request. | | +| `--client-authority` | No | **string** Temporal gRPC client :authority pseudoheader. | | +| `--client-connect-timeout` | No | **duration** The client connection timeout. 0s means no timeout. | | +| `--codec-auth` | No | **string** Authorization header for Codec Server requests. | | +| `--codec-endpoint` | No | **string** Remote Codec Server endpoint. | | +| `--codec-header` | No | **string[]** HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. | | +| `--color` | No | **string-enum** Output coloring. Accepted values: always, never, auto. | `auto` | +| `--command-timeout` | No | **duration** The command execution timeout. 0s means no timeout. | | +| `--config-file` | No | **string** File path to read TOML config from, defaults to `$CONFIG_PATH/temporalio/temporal.toml` where `$CONFIG_PATH` is defined as `$HOME/.config` on Unix, `$HOME/Library/Application Support` on macOS, and `%AppData%` on Windows. | | +| `--disable-config-env` | No | **bool** If set, disables loading environment config from environment variables. | | +| `--disable-config-file` | No | **bool** If set, disables loading environment config from config file. | | +| `--env` | No | **string** Active environment name (`ENV`). | `default` | +| `--env-file` | No | **string** Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`. | | +| `--grpc-meta` | No | **string[]** HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`. | | +| `--identity` | No | **string** The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST". | | +| `--log-format` | No | **string-enum** Log format. Accepted values: text, json. | `text` | +| `--log-level` | No | **string-enum** Log level. Default is "never" for most commands and "warn" for "server start-dev". Accepted values: debug, info, warn, error, never. | `never` | +| `--namespace`, `-n` | No | **string** Temporal Service Namespace. | `default` | +| `--no-json-shorthand-payloads` | No | **bool** Raw payload output, even if the JSON option was used. | | +| `--output`, `-o` | No | **string-enum** Non-logging data output format. Accepted values: text, json, jsonl, none. | `text` | +| `--profile` | No | **string** Profile to use for config file. | | +| `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | +| `--tls` | No | **bool** Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable. | | +| `--tls-ca-data` | No | **string** Data for server CA certificate. Can't be used with --tls-ca-path. | | +| `--tls-ca-path` | No | **string** Path to server CA certificate. Can't be used with --tls-ca-data. | | +| `--tls-cert-data` | No | **string** Data for x509 certificate. Can't be used with --tls-cert-path. | | +| `--tls-cert-path` | No | **string** Path to x509 certificate. Can't be used with --tls-cert-data. | | +| `--tls-disable-host-verification` | No | **bool** Disable TLS host-name verification. | | +| `--tls-key-data` | No | **string** Private certificate key data. Can't be used with --tls-key-path. | | +| `--tls-key-path` | No | **string** Path to x509 private key. Can't be used with --tls-key-data. | | +| `--tls-server-name` | No | **string** Override target TLS server name. | | + diff --git a/docs/cli/schedule.mdx b/docs/cli/schedule.mdx index 277c97848e..7945f7462e 100644 --- a/docs/cli/schedule.mdx +++ b/docs/cli/schedule.mdx @@ -194,6 +194,33 @@ Use the following options to change the behavior of this command. You can also u | `--query`, `-q` | No | **string** Filter results using given List Filter. | | `--really-long` | No | **bool** Show extensive information in non-table form. | +## list-matching-times + + +Note: This is an experimental feature and may change in the future. + +List the times a Schedule's spec would match within a given time +range. The time range may be in the past or future. Use this +command to preview when a Schedule will take actions without +actually running them. + +For example: + +``` + temporal schedule list-matching-times \ + --schedule-id "YourScheduleId" \ + --start-time "2024-01-01T00:00:00Z" \ + --end-time "2024-01-31T23:59:59Z" +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--end-time` | Yes | **timestamp** End of time range to list matching times. | +| `--schedule-id`, `-s` | Yes | **string** Schedule ID. | +| `--start-time` | Yes | **timestamp** Start of time range to list matching times. | + ## toggle Pause or unpause a Schedule by passing a flag with your desired state: diff --git a/docs/cli/task-queue.mdx b/docs/cli/task-queue.mdx index e03e1ee25a..3b822309db 100644 --- a/docs/cli/task-queue.mdx +++ b/docs/cli/task-queue.mdx @@ -70,8 +70,8 @@ temporal task-queue config set \ --queue-rps-limit-reason \ --fairness-key-rps-limit-default \ --fairness-key-rps-limit-reason \ - --fairness-key-weight-set HighPriority=2.0 \ - --fairness-key-weight-set LowPriority=0.5 + --fairness-key-weight HighPriority=2.0 \ + --fairness-key-weight LowPriority=0.5 ``` This command supports updating: @@ -85,8 +85,8 @@ This command supports updating: Weights control the relative share of capacity each key receives. To unset a rate limit, pass in 'default', for example: --queue-rps-limit default -To unset specific fairness weights, use --fairness-key-weight-unset \ -To unset all fairness weights, use --fairness-key-weight-unset-all +To unset a specific fairness weight, use --fairness-key-weight =default +To unset all fairness weights, use --fairness-key-weight-clear-all Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. @@ -412,9 +412,9 @@ Use the following options to change the behavior of this command. You can also u ## versioning ``` -+---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | -+---------------------------------------------------------------------+ ++-------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++-------------------------------------------------------------+ ``` Provides commands to add, list, remove, or replace Worker Build ID assignment @@ -438,6 +438,12 @@ Task Queues support the following versioning rules and policies: ### add-redirect-rule +``` ++-------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++-------------------------------------------------------------+ +``` + Add a new redirect rule for a given Task Queue. You may add at most one redirect rule for each distinct source build ID: @@ -448,12 +454,6 @@ temporal task-queue versioning add-redirect-rule \ --target-build-id "YourTargetBuildID" ``` -``` -+---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | -+---------------------------------------------------------------------+ -``` - Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. | Flag | Required | Description | @@ -464,6 +464,12 @@ Use the following options to change the behavior of this command. You can also u ### commit-build-id +``` ++-------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++-------------------------------------------------------------+ +``` + Complete a Build ID's rollout and clean up unnecessary rules that might have been created during a gradual rollout: @@ -485,12 +491,6 @@ 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. You can also use any of the [global flags](#global-flags) that apply to all subcommands. | Flag | Required | Description | @@ -501,6 +501,12 @@ Use the following options to change the behavior of this command. You can also u ### delete-assignment-rule +``` ++-------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++-------------------------------------------------------------+ +``` + Deletes a rule identified by its index in the Task Queue's list of assignment rules. @@ -514,12 +520,6 @@ 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. You can also use any of the [global flags](#global-flags) that apply to all subcommands. | Flag | Required | Description | @@ -530,6 +530,12 @@ Use the following options to change the behavior of this command. You can also u ### delete-redirect-rule +``` ++-------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++-------------------------------------------------------------+ +``` + Deletes the routing rule for the given source Build ID. ``` @@ -538,12 +544,6 @@ temporal task-queue versioning delete-redirect-rule \ --source-build-id "YourBuildId" ``` -``` -+---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | -+---------------------------------------------------------------------+ -``` - Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. | Flag | Required | Description | @@ -553,6 +553,12 @@ Use the following options to change the behavior of this command. You can also u ### get-rules +``` ++-------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++-------------------------------------------------------------+ +``` + Retrieve all the Worker Build ID assignments and redirect rules associated with a Task Queue: @@ -571,16 +577,17 @@ Task Queues support the following versioning rules: Build ID. You may add at most one redirect rule for each source Build ID. Redirect rules require that a target Build ID is fully compatible with the source Build ID. -``` -+---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | -+---------------------------------------------------------------------+ -``` Use [global flags](#global-flags) to customize the connection to the Temporal Service for this command. ### insert-assignment-rule +``` ++-------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++-------------------------------------------------------------+ +``` + 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: @@ -593,12 +600,6 @@ temporal task-queue versioning insert-assignment-rule \ If you do not specify a `--rule-index`, this command inserts at index 0. -``` -+---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | -+---------------------------------------------------------------------+ -``` - Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. | Flag | Required | Description | @@ -610,6 +611,12 @@ Use the following options to change the behavior of this command. You can also u ### replace-assignment-rule +``` ++-------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++-------------------------------------------------------------+ +``` + 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. @@ -636,12 +643,6 @@ temporal task-queue versioning replace-assignment-rule \ 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. You can also use any of the [global flags](#global-flags) that apply to all subcommands. | Flag | Required | Description | @@ -654,6 +655,12 @@ Use the following options to change the behavior of this command. You can also u ### replace-redirect-rule +``` ++-------------------------------------------------------------+ +| CAUTION: This API has been deprecated by Worker Deployment. | ++-------------------------------------------------------------+ +``` + Updates a Build ID's redirect rule on a Task Queue by replacing its target Build ID: @@ -664,12 +671,6 @@ temporal task-queue versioning replace-redirect-rule \ --target-build-id YourNewTargetBuildId ``` -``` -+---------------------------------------------------------------------+ -| CAUTION: This API has been deprecated by Worker Deployment. | -+---------------------------------------------------------------------+ -``` - Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. | Flag | Required | Description | diff --git a/docs/cli/workflow.mdx b/docs/cli/workflow.mdx index fa6cf08052..08ca40f62f 100644 --- a/docs/cli/workflow.mdx +++ b/docs/cli/workflow.mdx @@ -105,7 +105,7 @@ Use the following options to change the behavior of this command. You can also u ## delete -Delete a Workflow Executions and its Event History: +Delete a Workflow Execution and its Event History: ``` temporal workflow delete \ @@ -115,6 +115,11 @@ temporal workflow delete \ The removal executes asynchronously. If the Execution is Running, the Service terminates it before deletion. +WARNING: Deleting Workflow Executions in a global Namespace removes them from +all replicas. Requests sent to a passive cluster are forwarded to the active +cluster by default; to target the passive cluster directly, specify +`--grpc-meta xdc-redirection=false`. + Visit https://docs.temporal.io/visibility to read more about Search Attributes and Query creation. See `temporal batch --help` for a quick reference. @@ -691,7 +696,7 @@ Use the following options to change the behavior of this command. You can also u | Flag | Required | Description | |------|----------|-------------| -| `--concurrency` | No | **int** Number of Event Histories to fetch at a time. | +| `--concurrency` | No | **int** Number of Workflow Histories to fetch at a time. | | `--depth` | No | **int** Set depth for your Child Workflow fetches. Pass -1 to fetch child workflows at any depth. | | `--fold` | No | **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` | No | **bool** Disable folding. Fetch and display Child Workflows within the set depth. |