diff --git a/docs/cli/command-reference/activity.mdx b/docs/cli/command-reference/activity.mdx index e39b42fd69..846901568f 100644 --- a/docs/cli/command-reference/activity.mdx +++ b/docs/cli/command-reference/activity.mdx @@ -29,13 +29,28 @@ cancellation error will be raised when the next heartbeat response is received; if the Activity allows this error to propagate, the Activity transitions to canceled status. +A visibility Query lets you send bulk cancellations to Standalone Activity +Executions matching the results: + +``` +temporal activity cancel \ + --query YourQuery \ + --reason YourReason +``` + +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. You can also use any of the [global flags](#global-flags) that apply to all subcommands. | Flag | Required | Description | |------|----------|-------------| -| `--activity-id`, `-a` | Yes | **string** Activity ID. | -| `--reason` | No | **string** Reason for cancellation. | -| `--run-id`, `-r` | No | **string** Activity Run ID. If not set, targets the latest run. | +| `--activity-id`, `-a` | No | **string** Activity ID. You must set either --activity-id or --query. | +| `--query`, `-q` | No | **string** EXPERIMENTAL: Starts a batch Activity operation using an SQL-like `QUERY` List Filter. This behavior may change in the future. You must set either --activity-id or --query. | +| `--reason` | No | **string** Reason for cancellation. Also used as reason for batch operation with --query, which defaults to a message with the current user's name. | +| `--rps` | No | **float** Limit batch's requests per second. Only allowed when --query is present. | +| `--run-id`, `-r` | No | **string** Activity Run ID. If not set, targets the latest run. Only use with --activity-id. Cannot use with --query. | +| `--yes`, `-y` | No | **bool** Don't prompt to confirm. Only allowed when --query is present. | ## complete @@ -49,6 +64,9 @@ temporal activity complete \ --result '{"YourResultKey": "YourResultVal"}' ``` +Omit `--workflow-id` to target a Standalone Activity by Activity ID +and optional Run ID. + 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 | @@ -77,6 +95,40 @@ Use the following options to change the behavior of this command. You can also u |------|----------|-------------| | `--query`, `-q` | No | **string** Query to filter Activity Executions to count. | +## delete + +Delete a Standalone Activity Execution and its Event History. + +``` +temporal activity delete \ + --activity-id YourActivityId +``` + +The removal executes asynchronously. If the Execution is Running, the Service +terminates it before deletion. + +A visibility Query lets you send bulk delete to Standalone Activity +Executions matching the results: + +``` +temporal activity delete \ + --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. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--activity-id`, `-a` | No | **string** Activity ID. You must set either --activity-id or --query. | +| `--query`, `-q` | No | **string** EXPERIMENTAL: Starts a batch Activity operation using an SQL-like `QUERY` List Filter. This behavior may change in the future. You must set either --activity-id or --query. | +| `--reason` | No | **string** Reason for batch operation. Only use with --query. Defaults to a message with the current user's name. | +| `--rps` | No | **float** Limit batch's requests per second. Only allowed when --query is present. | +| `--run-id`, `-r` | No | **string** Activity Run ID. If not set, targets the latest run. Only use with --activity-id. Cannot use with --query. | +| `--yes`, `-y` | No | **bool** Don't prompt to confirm. | + ## describe Display information about a Standalone Activity. @@ -86,6 +138,8 @@ temporal activity describe \ --activity-id YourActivityId ``` +If `--run-id` is omitted, the latest Activity run is described. + 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 | @@ -108,6 +162,8 @@ temporal activity execute \ --input '{"some-key": "some-value"}' ``` +The command exits after the Activity completes. + 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 | @@ -131,6 +187,7 @@ Use the following options to change the behavior of this command. You can also u | `--schedule-to-close-timeout` | No | **duration** Maximum time for the Activity Execution, including all retries. Either this or "start-to-close-timeout" is required. | | `--schedule-to-start-timeout` | No | **duration** Maximum time an Activity task can stay in a task queue before a Worker picks it up. On expiry it results in a non-retryable failure and no further attempts are scheduled. | | `--search-attribute` | No | **string[]** Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. Can be passed multiple times. See https://docs.temporal.io/visibility. | +| `--start-delay` | No | **duration** Delay before dispatching the first Activity task. This delay is not applied to retry attempts. | | `--start-to-close-timeout` | No | **duration** Maximum time for a single Activity attempt. On expiry a new attempt may be scheduled if permitted by the retry policy and schedule-to-close timeout. Either this or "schedule-to-close-timeout" is required. | | `--static-details` | No | **string** Static Activity details for human consumption in UIs. Uses standard Markdown formatting excluding images, HTML, and script tags. _(Experimental)_ | | `--static-summary` | No | **string** Static Activity summary for human consumption in UIs. Uses standard Markdown formatting excluding images, HTML, and script tags. _(Experimental)_ | @@ -147,6 +204,9 @@ temporal activity fail \ --workflow-id YourWorkflowId ``` +Omit `--workflow-id` to target a Standalone Activity by Activity ID +and optional Run ID. + 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 | @@ -179,7 +239,9 @@ Use the following options to change the behavior of this command. You can also u ## pause -Pause an Activity. Not supported for Standalone Activities. +Pause an Activity. + +Note: This is an experimental feature and may change in the future. If the Activity is not currently running (e.g. because it previously failed), it will not be run again until it is unpaused. @@ -194,7 +256,7 @@ to extend timeout settings before a long pause. 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. -Specify the Activity and Workflow IDs: +To target a workflow Activity, specify the Activity and Workflow IDs: ``` temporal activity pause \ @@ -202,6 +264,14 @@ temporal activity pause \ --workflow-id YourWorkflowId ``` +To target a standalone Activity, specify the Activity and Run IDs: + +``` +temporal activity pause \ + --activity-id YourActivityId \ + --run-id YourRunId +``` + To later unpause the activity, see [unpause](#unpause). You may also want to [reset](#reset) the activity to unpause it while also starting it from the beginning. @@ -212,73 +282,80 @@ Use the following options to change the behavior of this command. You can also u | `--activity-id`, `-a` | No | **string** The Activity ID to pause. Required. | | `--identity` | No | **string** The identity of the user or client submitting this request. | | `--reason` | No | **string** Reason for pausing the Activity. | -| `--run-id`, `-r` | No | **string** Run ID. | -| `--workflow-id`, `-w` | Yes | **string** Workflow ID. | +| `--run-id`, `-r` | No | **string** Run ID. With --workflow-id, identifies the workflow run. For a standalone Activity (no --workflow-id), targets a specific run; omit to target the latest run. | +| `--workflow-id`, `-w` | No | **string** Workflow ID. Set to target a workflow Activity. Omit to target a standalone Activity. | ## reset -Reset an activity. Not supported for Standalone Activities. -This restarts the activity as if it were first being scheduled: the -attempt count returns to one, its per-attempt timeouts are re-armed, and -its [heartbeat details](#reset-heartbeats) are cleared. +Reset an Activity. + +Note: This is an experimental feature and may change in the future. -If the activity may be executing (i.e. it has not yet timed out), the +This restarts the Activity as if it were first being scheduled: the +attempt count returns to one, its per-attempt timeouts are re-armed. +Use `--clear-heartbeat-details` to also clear its +[heartbeat details](#clear-heartbeat-details). + +If the Activity may be executing (i.e. it has not yet timed out), the reset will take effect the next time it fails, heartbeats, or times out. -If is waiting for a retry (i.e. has failed or timed out), the reset +If the Activity is waiting for a retry (i.e. has failed or timed out), the reset will apply immediately. -If the activity is already paused, it will be unpaused by default. -You can specify `keep_paused` to prevent this. - -If the activity is paused and the `keep_paused` flag is not provided, -it will be unpaused. If the activity is paused and `keep_paused` flag -is provided - it will stay paused. +If the Activity is already paused, it will be unpaused by default. +You can specify `--keep-paused` to prevent this. -Either `--activity-id` (with `--workflow-id`) or `--query` must be specified. +Either `--activity-id` (with `--workflow-id` for a workflow Activity, or +alone for a standalone Activity) or `--query` must be specified. -### Resetting activities that heartbeat {/* #reset-heartbeats */} +### Resetting activities that heartbeat {/* #clear-heartbeat-details */} -Activities that heartbeat will receive a [Canceled failure](/references/failures#cancelled-failure) -the next time they heartbeat after a reset. +Activities that heartbeat will receive a +[Canceled failure](/references/failures#cancelled-failure) the next time +they heartbeat after a reset. If, in your Activity, you need to do any cleanup when an Activity is reset, handle this error and then re-throw it when you've cleaned up. -If the `reset_heartbeats` flag is set, the heartbeat details will also be cleared. +Use `--clear-heartbeat-details` to clear the heartbeat details as part of +the reset. Specify the Activity and Workflow IDs: ``` temporal activity reset \ --activity-id YourActivityId \ - --workflow-id YourWorkflowId + --workflow-id YourWorkflowId \ --keep-paused - --reset-heartbeats ``` -Activities can be reset in bulk with a visibility query list filter: +Workflow Activities can be reset in bulk with a visibility query list filter: ``` temporal activity reset \ --query 'WorkflowType="YourWorkflow"' ``` +The `--query` flag currently applies only to Workflow Activities. + +Omit `--workflow-id` to target a Standalone Activity by Activity ID +and optional Run ID. + 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 | |------|----------|-------------| -| `--activity-id`, `-a` | No | **string** The Activity ID to reset. Mutually exclusive with `--query`. Requires `--workflow-id` to be specified. | +| `--activity-id`, `-a` | No | **string** The Activity ID to reset. Mutually exclusive with `--query`. Set `--workflow-id` to target a workflow Activity, or omit it to target a standalone Activity (the latest run unless `--run-id` is set). | +| `--clear-heartbeat-details` | No | **bool** Clear the Activity's heartbeat details. | | `--headers` | No | **string[]** Temporal workflow headers in 'KEY=VALUE' format. Keys must be identifiers, and values must be JSON values. May be passed multiple times to set multiple Temporal headers. Note: These are workflow headers, not gRPC headers. | | `--jitter` | No | **duration** The activity will reset at random a time within the specified duration. Can only be used with --query. | | `--keep-paused` | No | **bool** If the activity was paused, it will stay paused. | -| `--query`, `-q` | No | **string** Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query. Note: Using --query for batch activity operations is an experimental feature and may change in the future. | +| `--query`, `-q` | No | **string** EXPERIMENTAL: Starts a batch Activity operation using an SQL-like `QUERY` List Filter. This behavior may change in the future. Set either --activity-id (single Activity) or --query (batch). --query cannot be combined with --workflow-id or --run-id. | | `--reason` | No | **string** Reason for batch operation. Only use with --query. Defaults to user name. | -| `--reset-heartbeats` | No | **bool** Reset the Activity's heartbeats. | | `--restore-original-options` | No | **bool** Restore the original options of the activity. | -| `--rps` | No | **float** Limit batch's requests per second. Only allowed if query is present. | -| `--run-id`, `-r` | No | **string** Run ID. Only use with --workflow-id. Cannot use with --query. | -| `--workflow-id`, `-w` | No | **string** Workflow ID. You must set either --workflow-id or --query. | -| `--yes`, `-y` | No | **bool** Don't prompt to confirm signaling. Only allowed when --query is present. | +| `--rps` | No | **float** Limit batch's requests per second. Only allowed when --query is present. | +| `--run-id`, `-r` | No | **string** Run ID. Only use with --workflow-id or --activity-id. Cannot use with --query. | +| `--workflow-id`, `-w` | No | **string** Workflow ID. Set to target a Workflow Activity. Omit to target a standalone Activity (by --activity-id). Only for Workflow Activities; cannot be combined with --query. | +| `--yes`, `-y` | No | **bool** Don't prompt to confirm the batch operation. Only allowed when --query is present. | ## result @@ -290,6 +367,8 @@ temporal activity result \ --activity-id YourActivityId ``` +If `--run-id` is omitted, the latest Activity run is used. + 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 | @@ -311,6 +390,8 @@ temporal activity start \ --input '{"some-key": "some-value"}' ``` +The command returns the Activity ID and Run ID. + 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 | @@ -334,6 +415,7 @@ Use the following options to change the behavior of this command. You can also u | `--schedule-to-close-timeout` | No | **duration** Maximum time for the Activity Execution, including all retries. Either this or "start-to-close-timeout" is required. | | `--schedule-to-start-timeout` | No | **duration** Maximum time an Activity task can stay in a task queue before a Worker picks it up. On expiry it results in a non-retryable failure and no further attempts are scheduled. | | `--search-attribute` | No | **string[]** Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. Can be passed multiple times. See https://docs.temporal.io/visibility. | +| `--start-delay` | No | **duration** Delay before dispatching the first Activity task. This delay is not applied to retry attempts. | | `--start-to-close-timeout` | No | **duration** Maximum time for a single Activity attempt. On expiry a new attempt may be scheduled if permitted by the retry policy and schedule-to-close timeout. Either this or "schedule-to-close-timeout" is required. | | `--static-details` | No | **string** Static Activity details for human consumption in UIs. Uses standard Markdown formatting excluding images, HTML, and script tags. _(Experimental)_ | | `--static-summary` | No | **string** Static Activity summary for human consumption in UIs. Uses standard Markdown formatting excluding images, HTML, and script tags. _(Experimental)_ | @@ -352,31 +434,41 @@ temporal activity terminate \ Activity code cannot see or respond to terminations. +A visibility Query lets you send bulk terminations to Standalone Activity +Executions matching the results: + +``` +temporal activity terminate \ + --query YourQuery \ + --reason YourReason +``` + +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. You can also use any of the [global flags](#global-flags) that apply to all subcommands. | Flag | Required | Description | |------|----------|-------------| -| `--activity-id`, `-a` | Yes | **string** Activity ID. | -| `--reason` | No | **string** Reason for termination. Defaults to a message with the current user's name. | -| `--run-id`, `-r` | No | **string** Activity Run ID. If not set, targets the latest run. | +| `--activity-id`, `-a` | No | **string** Activity ID. You must set either --activity-id or --query. | +| `--query`, `-q` | No | **string** EXPERIMENTAL: Starts a batch Activity operation using an SQL-like `QUERY` List Filter. This behavior may change in the future. You must set either --activity-id or --query. | +| `--reason` | No | **string** Reason for termination. Defaults to a message with the current user's name. Also used as reason for batch operation with --query. | +| `--rps` | No | **float** Limit batch's requests per second. Only allowed when --query is present. | +| `--run-id`, `-r` | No | **string** Activity Run ID. If not set, targets the latest run. Only use with --activity-id. Cannot use with --query. | +| `--yes`, `-y` | No | **bool** Don't prompt to confirm. Only allowed when --query is present. | ## unpause Re-schedule a previously-paused Activity for execution. -Not supported for Standalone Activities. + +Note: This is an experimental feature and may change in the future. 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. - -Either `--activity-id` (with `--workflow-id`) or `--query` must be specified. +Either `--activity-id` (with `--workflow-id` for a workflow Activity, or +alone for a standalone Activity) or `--query` must be specified. Specify the Activity and Workflow IDs: @@ -384,38 +476,40 @@ Specify the Activity and Workflow IDs: temporal activity unpause \ --activity-id YourActivityId \ --workflow-id YourWorkflowId - --reset-attempts - --reset-heartbeats ``` -Activities can be unpaused in bulk via a visibility Query list filter: +Workflow Activities can be unpaused in bulk via a visibility Query list filter: ``` temporal activity unpause \ --query 'TemporalPauseInfo IS NOT NULL' ``` +The `--query` flag currently applies only to Workflow Activities. + +Omit `--workflow-id` to target a Standalone Activity by Activity ID +and optional Run ID. + 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 | |------|----------|-------------| -| `--activity-id`, `-a` | No | **string** The Activity ID to unpause. Mutually exclusive with `--query`. Requires `--workflow-id` to be specified. | +| `--activity-id`, `-a` | No | **string** The Activity ID to unpause. Mutually exclusive with `--query`. Set `--workflow-id` to target a workflow Activity, or omit it to target a standalone Activity (the latest run unless `--run-id` is set). | | `--headers` | No | **string[]** Temporal workflow headers in 'KEY=VALUE' format. Keys must be identifiers, and values must be JSON values. May be passed multiple times to set multiple Temporal headers. Note: These are workflow headers, not gRPC headers. | | `--jitter` | No | **duration** The activity will start at random a time within the specified duration. Can only be used with --query. | -| `--query`, `-q` | No | **string** Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query. Note: Using --query for batch activity operations is an experimental feature and may change in the future. | +| `--query`, `-q` | No | **string** EXPERIMENTAL: Starts a batch Activity operation using an SQL-like `QUERY` List Filter. This behavior may change in the future. Set either --activity-id (single Activity) or --query (batch). --query cannot be combined with --workflow-id or --run-id. | | `--reason` | No | **string** Reason for batch operation. Only use with --query. Defaults to user name. | -| `--reset-attempts` | No | **bool** Reset the activity attempts. | -| `--reset-heartbeats` | No | **bool** Reset the Activity's heartbeats. | -| `--rps` | No | **float** Limit batch's requests per second. Only allowed if query is present. | -| `--run-id`, `-r` | No | **string** Run ID. Only use with --workflow-id. Cannot use with --query. | -| `--workflow-id`, `-w` | No | **string** Workflow ID. You must set either --workflow-id or --query. | -| `--yes`, `-y` | No | **bool** Don't prompt to confirm signaling. Only allowed when --query is present. | +| `--rps` | No | **float** Limit batch's requests per second. Only allowed when --query is present. | +| `--run-id`, `-r` | No | **string** Run ID. Only use with --workflow-id or --activity-id. Cannot use with --query. | +| `--workflow-id`, `-w` | No | **string** Workflow ID. Set to target a Workflow Activity. Omit to target a standalone Activity (by --activity-id). Only for Workflow Activities; cannot be combined with --query. | +| `--yes`, `-y` | No | **bool** Don't prompt to confirm the batch operation. Only allowed when --query is present. | ## update-options -Update the options of a running Activity that were passed into it from -a Workflow. Updates are incremental, only changing the specified options. -Not supported for Standalone Activities. +Update an Activity's options. Updates are incremental, only changing the +specified options. + +Note: This is an experimental feature and may change in the future. For example: @@ -434,11 +528,19 @@ temporal activity update-options \ --retry-maximum-attempts NewMaximumAttempts ``` -You may follow this command with `temporal activity reset`, and the new values will apply after the reset. +You may follow this command with `temporal activity reset`, and the new +values will apply after the reset. + +For a Standalone Activity before its first dispatch, use `--start-delay` +to change when the first Activity Task becomes available. The duration is +measured from the Activity's original schedule time, and `0s` makes it +available immediately. `--start-delay` cannot be changed after the first +Activity Task has been dispatched and is not supported for workflow +Activities. Either `--activity-id` or `--query` must be specified. -Activity options can be updated in bulk with a visibility query list filter: +Workflow Activity options can be updated in bulk with a visibility query list filter: ``` temporal activity update-options \ @@ -446,28 +548,34 @@ temporal activity update-options \ --task-queue NewTaskQueueName ``` +The `--query` flag currently applies only to Workflow Activities. + +Omit `--workflow-id` to target a Standalone Activity by Activity ID +and optional Run ID. + 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 | |------|----------|-------------| -| `--activity-id`, `-a` | No | **string** The Activity ID to update options. Mutually exclusive with `--query`. Requires `--workflow-id` to be specified. | +| `--activity-id`, `-a` | No | **string** The Activity ID to update options. Mutually exclusive with `--query`. Set `--workflow-id` to target a workflow Activity, or omit it to target a standalone Activity (the latest run unless `--run-id` is set). | | `--headers` | No | **string[]** Temporal workflow headers in 'KEY=VALUE' format. Keys must be identifiers, and values must be JSON values. May be passed multiple times to set multiple Temporal headers. Note: These are workflow headers, not gRPC headers. | | `--heartbeat-timeout` | No | **duration** Maximum permitted time between successful worker heartbeats. | -| `--query`, `-q` | No | **string** Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query. Note: Using --query for batch activity operations is an experimental feature and may change in the future. | +| `--query`, `-q` | No | **string** EXPERIMENTAL: Starts a batch Activity operation using an SQL-like `QUERY` List Filter. This behavior may change in the future. Set either --activity-id (single Activity) or --query (batch). --query cannot be combined with --workflow-id or --run-id. | | `--reason` | No | **string** Reason for batch operation. Only use with --query. Defaults to user name. | | `--restore-original-options` | No | **bool** Restore the original options of the activity. | | `--retry-backoff-coefficient` | No | **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` | No | **duration** Interval of the first retry. If retryBackoffCoefficient is 1.0 then it is used for all retries. | -| `--retry-maximum-attempts` | No | **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-attempts` | No | **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` | No | **duration** Maximum interval between retries. Exponential backoff leads to interval increase. This value is the cap of the increase. | -| `--rps` | No | **float** Limit batch's requests per second. Only allowed if query is present. | -| `--run-id`, `-r` | No | **string** Run ID. Only use with --workflow-id. Cannot use with --query. | +| `--rps` | No | **float** Limit batch's requests per second. Only allowed when --query is present. | +| `--run-id`, `-r` | No | **string** Run ID. Only use with --workflow-id or --activity-id. Cannot use with --query. | | `--schedule-to-close-timeout` | No | **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` | No | **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-delay` | No | **duration** For a Standalone Activity before its first Activity Task is dispatched, changes when that task becomes available. The duration is measured from the Activity's original schedule time. Set to `0s` to make the task available immediately. | | `--start-to-close-timeout` | No | **duration** Maximum time an activity is allowed to execute after being picked up by a worker. This timeout is always retryable. | | `--task-queue` | No | **string** Name of the task queue for the Activity. | -| `--workflow-id`, `-w` | No | **string** Workflow ID. You must set either --workflow-id or --query. | -| `--yes`, `-y` | No | **bool** Don't prompt to confirm signaling. Only allowed when --query is present. | +| `--workflow-id`, `-w` | No | **string** Workflow ID. Set to target a Workflow Activity. Omit to target a standalone Activity (by --activity-id). Only for Workflow Activities; cannot be combined with --query. | +| `--yes`, `-y` | No | **bool** Don't prompt to confirm the batch operation. Only allowed when --query is present. | ## Global Flags @@ -496,7 +604,7 @@ The following options can be used with any command. | `--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. | | +| `--profile` | No | **string** Configuration profile to use. Overrides the TEMPORAL_PROFILE environment variable and defaults to "default". | | | `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | | `--tls` | No | **bool** Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. | | | `--tls-ca-data` | No | **string** Inline server CA certificate data. | | diff --git a/docs/cli/command-reference/batch.mdx b/docs/cli/command-reference/batch.mdx index bf5691edf4..30ee2a90d4 100644 --- a/docs/cli/command-reference/batch.mdx +++ b/docs/cli/command-reference/batch.mdx @@ -2,7 +2,7 @@ id: batch title: Temporal CLI batch command reference sidebar_label: batch -description: Use Temporal CLI to manage multiple Workflow Executions with Batch Jobs that can Cancel, Signal, or Terminate Workflows. Filter and monitor Batch Jobs effectively. +description: Use Temporal CLI to manage multiple Workflow or Standalone Activity Executions with Batch Jobs. Filter and monitor Batch Jobs effectively. toc_max_heading_level: 4 tags: - Temporal CLI @@ -91,7 +91,7 @@ The following options can be used with any command. | `--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. | | +| `--profile` | No | **string** Configuration profile to use. Overrides the TEMPORAL_PROFILE environment variable and defaults to "default". | | | `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | | `--tls` | No | **bool** Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. | | | `--tls-ca-data` | No | **string** Inline server CA certificate data. | | diff --git a/docs/cli/command-reference/cloud/connectivity.mdx b/docs/cli/command-reference/cloud/connectivity.mdx index 90db6e6329..492b4449fe 100644 --- a/docs/cli/command-reference/cloud/connectivity.mdx +++ b/docs/cli/command-reference/cloud/connectivity.mdx @@ -110,7 +110,7 @@ Use the following options to change the behavior of this command. You can also u | `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | | `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | | `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | -| `--azure-pe-resource-id` | No | **string** The ARM resource ID of the Azure Private Endpoint (only for Azure private connectivity). Example: `/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Network/privateEndpoints/{name}`. | +| `--azure-pe-resource-id` | No | **string** The ARM resource ID of the Azure Private Endpoint (only for Azure private connectivity). Example: /subscriptions/\{sub\}/resourceGroups/\{rg\}/providers/Microsoft.Network/privateEndpoints/\{name\}. | | `--connection-id` | No | **string** The connection ID for private connectivity (AWS VPC endpoint ID or GCP PSC connection ID). | | `--gcp-project-id` | No | **string** The GCP project ID (only for GCP private connectivity). | | `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | @@ -157,3 +157,4 @@ The following options can be used with any command. | `--config-dir` | No | **string** Directory path where CLI configuration files are stored, including authentication tokens and settings. | | | `--disable-pop-up` | No | **bool** Prevent the CLI from opening a browser window during authentication. Useful for headless environments or when using alternative auth methods. | | | `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | `saas-api.tmprl.cloud:443` | + diff --git a/docs/cli/command-reference/config.mdx b/docs/cli/command-reference/config.mdx index c65c32c4bd..04953fe053 100644 --- a/docs/cli/command-reference/config.mdx +++ b/docs/cli/command-reference/config.mdx @@ -19,6 +19,7 @@ Remove a property within a profile. ``` temporal config delete \ + --profile YourProfile \ --prop tls.client_cert_path ``` @@ -34,7 +35,7 @@ Remove a full profile entirely. The `--profile` must be set explicitly. ``` temporal config delete-profile \ - --profile my-profile + --profile YourProfile ``` Use [global flags](#global-flags) to customize the connection to the Temporal Service for this command. @@ -45,6 +46,7 @@ Display specific properties or the entire profile. ``` temporal config get \ + --profile YourProfile \ --prop address ``` @@ -76,6 +78,7 @@ Assign a value to a property and store it in the config file: ``` temporal config set \ + --profile YourProfile \ --prop address \ --value us-west-2.aws.api.temporal.io:7233 ``` @@ -114,7 +117,7 @@ The following options can be used with any command. | `--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. | | +| `--profile` | No | **string** Configuration profile to use. Overrides the TEMPORAL_PROFILE environment variable and defaults to "default". | | | `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | | `--tls` | No | **bool** Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. | | | `--tls-ca-data` | No | **string** Inline server CA certificate data. | | diff --git a/docs/cli/command-reference/env.mdx b/docs/cli/command-reference/env.mdx index 0ce784a7f2..f06ad59549 100644 --- a/docs/cli/command-reference/env.mdx +++ b/docs/cli/command-reference/env.mdx @@ -125,7 +125,7 @@ The following options can be used with any command. | `--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. | | +| `--profile` | No | **string** Configuration profile to use. Overrides the TEMPORAL_PROFILE environment variable and defaults to "default". | | | `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | | `--tls` | No | **bool** Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. | | | `--tls-ca-data` | No | **string** Inline server CA certificate data. | | diff --git a/docs/cli/command-reference/index.mdx b/docs/cli/command-reference/index.mdx index da071acbf1..e9b5d37bfa 100644 --- a/docs/cli/command-reference/index.mdx +++ b/docs/cli/command-reference/index.mdx @@ -16,6 +16,7 @@ This section includes the complete command reference for the `temporal` CLI, inc - [cloud](/cli/command-reference/cloud) - [config](/cli/command-reference/config) - [env](/cli/command-reference/env) +- [nexus](/cli/command-reference/nexus) - [operator](/cli/command-reference/operator) - [schedule](/cli/command-reference/schedule) - [server](/cli/command-reference/server) diff --git a/docs/cli/command-reference/nexus.mdx b/docs/cli/command-reference/nexus.mdx new file mode 100644 index 0000000000..f6b1ef86a8 --- /dev/null +++ b/docs/cli/command-reference/nexus.mdx @@ -0,0 +1,247 @@ +--- +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 +tags: + - Nexus + - Temporal CLI +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from the CLI command definitions via 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 'Endpoint="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` | Yes | **string** Nexus Operation ID. | +| `--schedule-to-close-timeout` | No | **duration** Total time the operation is allowed to run. | +| `--schedule-to-start-timeout` | No | **duration** Maximum time to wait for an operation to be started (or completed synchronously) by a handler. | +| `--search-attribute` | No | **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. | +| `--service` | Yes | **string** Nexus Service name. | +| `--start-to-close-timeout` | No | **duration** Maximum time to wait for an asynchronous operation to complete after it has been started. | +| `--static-summary` | No | **string** Static summary for the Nexus Operation for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line. _(Experimental)_ | + +### list + +List Nexus Operations. Use `--query` to filter results. + +``` +temporal nexus operation list \ + --query 'Endpoint="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` | Yes | **string** Nexus Operation ID. | +| `--schedule-to-close-timeout` | No | **duration** Total time the operation is allowed to run. | +| `--schedule-to-start-timeout` | No | **duration** Maximum time to wait for an operation to be started (or completed synchronously) by a handler. | +| `--search-attribute` | No | **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. | +| `--service` | Yes | **string** Nexus Service name. | +| `--start-to-close-timeout` | No | **duration** Maximum time to wait for an asynchronous operation to complete after it has been started. | +| `--static-summary` | No | **string** Static summary for the Nexus Operation for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line. _(Experimental)_ | + +### 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** Client connection 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 codec server (KEY=VALUE, repeatable). | | +| `--color` | No | **string-enum** Output coloring. Accepted values: always, never, auto. | `auto` | +| `--command-timeout` | No | **duration** Command execution timeout. | | +| `--config-file` | No | **string** TOML config file path. | | +| `--disable-config-env` | No | **bool** Disable loading config from environment variables. | | +| `--disable-config-file` | No | **bool** Disable loading config from file. | | +| `--env` | No | **string** Active environment name (`ENV`). | `default` | +| `--env-file` | No | **string** Path to environment settings file. | | +| `--grpc-meta` | No | **string[]** HTTP headers for requests (KEY=VALUE, repeatable). | | +| `--identity` | No | **string** Identity of the client submitting requests. | | +| `--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** Configuration profile to use. Overrides the TEMPORAL_PROFILE environment variable and defaults to "default". | | +| `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | +| `--tls` | No | **bool** Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. | | +| `--tls-ca-data` | No | **string** Inline server CA certificate data. | | +| `--tls-ca-path` | No | **string** Path to server CA certificate. | | +| `--tls-cert-data` | No | **string** Inline x509 certificate data. | | +| `--tls-cert-path` | No | **string** Path to x509 certificate. | | +| `--tls-disable-host-verification` | No | **bool** Disable TLS host-name verification. | | +| `--tls-key-data` | No | **string** Inline x509 private key data. | | +| `--tls-key-path` | No | **string** Path to x509 private key. | | +| `--tls-server-name` | No | **string** Override target TLS server name. | | + diff --git a/docs/cli/command-reference/operator.mdx b/docs/cli/command-reference/operator.mdx index 2ace4e7fd0..05e567f246 100644 --- a/docs/cli/command-reference/operator.mdx +++ b/docs/cli/command-reference/operator.mdx @@ -204,7 +204,7 @@ Use the following options to change the behavior of this command. You can also u | Flag | Required | Description | |------|----------|-------------| -| `--yes`, `-y` | No | **bool** Request confirmation before deletion. | +| `--yes`, `-y` | No | **bool** Don't prompt to confirm deletion. | ### describe @@ -515,7 +515,7 @@ The following options can be used with any command. | `--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. | | +| `--profile` | No | **string** Configuration profile to use. Overrides the TEMPORAL_PROFILE environment variable and defaults to "default". | | | `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | | `--tls` | No | **bool** Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. | | | `--tls-ca-data` | No | **string** Inline server CA certificate data. | | diff --git a/docs/cli/command-reference/schedule.mdx b/docs/cli/command-reference/schedule.mdx index 945fb1a01e..562d19b7ed 100644 --- a/docs/cli/command-reference/schedule.mdx +++ b/docs/cli/command-reference/schedule.mdx @@ -2,7 +2,7 @@ id: schedule title: Temporal CLI schedule command reference sidebar_label: schedule -description: Temporal's Schedule commands create, update, and manage scheduled Workflow Executions, including creation, backfill, and deletion. +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 tags: - Temporal CLI @@ -263,7 +263,9 @@ specifications, action, and policies: ``` temporal schedule update \ --schedule-id "YourScheduleId" \ - --workflow-type "NewWorkflowType" + --workflow-id YourBaseWorkflowIdName \ + --task-queue YourTaskQueue \ + --type YourWorkflowType ``` This command performs a full replacement of the Schedule @@ -340,7 +342,7 @@ The following options can be used with any command. | `--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. | | +| `--profile` | No | **string** Configuration profile to use. Overrides the TEMPORAL_PROFILE environment variable and defaults to "default". | | | `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | | `--tls` | No | **bool** Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. | | | `--tls-ca-data` | No | **string** Inline server CA certificate data. | | diff --git a/docs/cli/command-reference/server.mdx b/docs/cli/command-reference/server.mdx index 893857b362..5ffe2fd2c3 100644 --- a/docs/cli/command-reference/server.mdx +++ b/docs/cli/command-reference/server.mdx @@ -105,7 +105,7 @@ The following options can be used with any command. | `--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. | | +| `--profile` | No | **string** Configuration profile to use. Overrides the TEMPORAL_PROFILE environment variable and defaults to "default". | | | `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | | `--tls` | No | **bool** Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. | | | `--tls-ca-data` | No | **string** Inline server CA certificate data. | | diff --git a/docs/cli/command-reference/task-queue.mdx b/docs/cli/command-reference/task-queue.mdx index a084354b49..a3c1b1103d 100644 --- a/docs/cli/command-reference/task-queue.mdx +++ b/docs/cli/command-reference/task-queue.mdx @@ -699,7 +699,7 @@ The following options can be used with any command. | `--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. | | +| `--profile` | No | **string** Configuration profile to use. Overrides the TEMPORAL_PROFILE environment variable and defaults to "default". | | | `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | | `--tls` | No | **bool** Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. | | | `--tls-ca-data` | No | **string** Inline server CA certificate data. | | diff --git a/docs/cli/command-reference/worker.mdx b/docs/cli/command-reference/worker.mdx index f06b9864da..00d881a10b 100644 --- a/docs/cli/command-reference/worker.mdx +++ b/docs/cli/command-reference/worker.mdx @@ -13,6 +13,21 @@ This file is generated from the CLI command definitions via cmd/gen-docs. */} This page provides a reference for the `temporal` CLI `worker` 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. +## count + +Show a count of workers in a namespace. Use `--query` to count a subset: + +``` +temporal worker count --namespace YourNamespace --query 'TaskQueue="YourTaskQueue"' +``` + +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 | +|------|----------|-------------| +| `--include-system-workers` | No | **bool** Include system workers created by the server. | +| `--query`, `-q` | No | **string** Content for an SQL-like `QUERY` List Filter. | + ## deployment Deployment commands perform operations on Worker Deployments: @@ -646,6 +661,7 @@ Use the following options to change the behavior of this command. You can also u | Flag | Required | Description | |------|----------|-------------| +| `--include-system-workers` | No | **bool** Include system workers that are created implicitly by the server. By default, system workers are excluded. | | `--limit` | No | **int** Maximum number of workers to display. | | `--query`, `-q` | No | **string** Content for an SQL-like `QUERY` List Filter. | @@ -676,7 +692,7 @@ The following options can be used with any command. | `--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. | | +| `--profile` | No | **string** Configuration profile to use. Overrides the TEMPORAL_PROFILE environment variable and defaults to "default". | | | `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | | `--tls` | No | **bool** Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. | | | `--tls-ca-data` | No | **string** Inline server CA certificate data. | | diff --git a/docs/cli/command-reference/workflow.mdx b/docs/cli/command-reference/workflow.mdx index 548ced223e..b2ff5867c3 100644 --- a/docs/cli/command-reference/workflow.mdx +++ b/docs/cli/command-reference/workflow.mdx @@ -370,9 +370,9 @@ Use the following options to change the behavior of this command. You can also u | Flag | Required | Description | |------|----------|-------------| -| `--versioning-override-behavior` | Yes | **string-enum** Override the versioning behavior of a Workflow. Accepted values: pinned, auto_upgrade. | -| `--versioning-override-build-id` | No | **string** When overriding to a `pinned` behavior, specifies the Build ID of the version to target. | -| `--versioning-override-deployment-name` | No | **string** When overriding to a `pinned` behavior, specifies the Deployment Name of the version to target. | +| `--versioning-override-behavior` | Yes | **string-enum** Override the versioning behavior of a Workflow. Accepted values: pinned, one_time, auto_upgrade. | +| `--versioning-override-build-id` | No | **string** When overriding to a `pinned` or `one_time` behavior, specifies the Build ID of the version to target. | +| `--versioning-override-deployment-name` | No | **string** When overriding to a `pinned` or `one_time` behavior, specifies the Deployment Name of the version to target. | ## result @@ -815,6 +815,17 @@ temporal workflow update-options \ --versioning-override-build-id YourDeploymentBuildId ``` +or to move the workflow execution to a Worker Deployment Version until +the next Workflow Task completes there, set behavior to `one_time`: + +``` +temporal workflow update-options \ + --workflow-id YourWorkflowId \ + --versioning-override-behavior one_time \ + --versioning-override-deployment-name YourDeploymentName \ + --versioning-override-build-id YourDeploymentBuildId +``` + To remove any previous overrides, set the behavior to `unspecified`: @@ -835,9 +846,9 @@ Use the following options to change the behavior of this command. You can also u | `--reason` | No | **string** Reason for batch operation. Only use with --query. Defaults to user name. | | `--rps` | No | **float** Limit batch's requests per second. Only allowed if query is present. | | `--run-id`, `-r` | No | **string** Run ID. Only use with --workflow-id. Cannot use with --query. | -| `--versioning-override-behavior` | Yes | **string-enum** Override the versioning behavior of a Workflow. Accepted values: unspecified, pinned, auto_upgrade. | -| `--versioning-override-build-id` | No | **string** When overriding to a `pinned` behavior, specifies the Build ID of the version to target. | -| `--versioning-override-deployment-name` | No | **string** When overriding to a `pinned` behavior, specifies the Deployment Name of the version to target. | +| `--versioning-override-behavior` | Yes | **string-enum** Override the versioning behavior of a Workflow. Accepted values: unspecified, pinned, one_time, auto_upgrade. | +| `--versioning-override-build-id` | No | **string** When overriding to a `pinned` or `one_time` behavior, specifies the Build ID of the version to target. | +| `--versioning-override-deployment-name` | No | **string** When overriding to a `pinned` or `one_time` behavior, specifies the Deployment Name of the version to target. | | `--workflow-id`, `-w` | No | **string** Workflow ID. You must set either --workflow-id or --query. | | `--yes`, `-y` | No | **bool** Don't prompt to confirm signaling. Only allowed when --query is present. | @@ -868,7 +879,7 @@ The following options can be used with any command. | `--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. | | +| `--profile` | No | **string** Configuration profile to use. Overrides the TEMPORAL_PROFILE environment variable and defaults to "default". | | | `--time-format` | No | **string-enum** Time format. Accepted values: relative, iso, raw. | `relative` | | `--tls` | No | **bool** Enable base TLS encryption. Auto-enabled when api-key or TLS options are set. | | | `--tls-ca-data` | No | **string** Inline server CA certificate data. | | diff --git a/sidebars.js b/sidebars.js index ba42163641..d2e121f58c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1684,6 +1684,7 @@ module.exports = { }, 'cli/command-reference/config', 'cli/command-reference/env', + 'cli/command-reference/nexus', 'cli/command-reference/operator', 'cli/command-reference/schedule', 'cli/command-reference/server',