Temporal CLI task-queue command reference

config

Manage Task Queue configuration:

temporal task-queue config [command] [options]

Available commands:

get: Retrieve the current configuration for a task queue
set: Update the configuration for a task queue

get

Retrieve the current configuration for a Task Queue:

temporal task-queue config get \
    --task-queue YourTaskQueue \
    --task-queue-type activity

This command returns the current configuration including:

Queue rate limit: The overall rate limit of the task queue. This setting overrides the worker rate limit if set. Unless modified, this is the system-defined rate limit.
Fairness key rate limit defaults: Default rate limits for fairness keys. If set, each individual fairness key will be limited to this rate, scaled by the weight of the fairness key.

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
`--task-queue`, `-t`	Yes	string Task Queue name.
`--task-queue-type`	Yes	string-enum Task Queue type. Accepted values: workflow, activity, nexus. Accepted values: workflow, activity, nexus.

set

Update configuration settings for a Task Queue.

temporal task-queue config set \
    --task-queue YourTaskQueue \
    --task-queue-type activity \
    --namespace YourNamespace \
    --queue-rps-limit <requests_per_second:float> \
    --queue-rps-limit-reason <reason_string> \
    --fairness-key-rps-limit-default <requests_per_second:float> \
    --fairness-key-rps-limit-reason <reason_string>

This command supports updating:

Queue rate limits: Controls the overall rate limit of the task queue. This setting overrides the worker rate limit if set. Unless modified, this is the system-defined rate limit.
Fairness key rate limit defaults: Sets default rate limits for fairness keys. If set, each individual fairness key will be limited to this rate, scaled by the weight of the fairness key.

To unset a rate limit, pass in 'default', for example: --queue-rps-limit default

Use the following options to change the behavior of this command.

Flag	Required	Description
`--fairness-key-rps-limit-default`	No	float\|default Fairness key rate limit default in requests per second. Accepts a float; or 'default' to unset.
`--fairness-key-rps-limit-reason`	No	string Reason for fairness key rate limit update.
`--queue-rps-limit`	No	float\|default Queue rate limit in requests per second. Accepts a float; or 'default' to unset.
`--queue-rps-limit-reason`	No	string Reason for queue rate limit update.
`--task-queue`, `-t`	Yes	string Task Queue name.
`--task-queue-type`	Yes	string-enum Task Queue type. Accepted values: workflow, activity, nexus. Accepted values: workflow, activity, nexus.

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 \
    --select-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.

Flag	Required	Description	Default
`--disable-stats`	No	bool Disable task queue statistics.
`--legacy-mode`	No	bool Enable a legacy mode for servers that do not support rules-based worker versioning. This mode only provides pollers info.
`--partitions-legacy`	No	int Query partitions 1 through `N`. Experimental/Temporary feature. Legacy mode only.	`1`
`--report-config`	No	bool Include task queue configuration in the response. When enabled, the command will return the current rate limit configuration for the task queue.
`--report-reachability`	No	bool Display task reachability information.
`--select-all-active`	No	bool Include all active versions. A version is active if it had new tasks or polls recently.
`--select-build-id`	No	string[] Filter the Task Queue based on Build ID.
`--select-unversioned`	No	bool Include the unversioned queue.
`--task-queue`, `-t`	Yes	string Task Queue name.
`--task-queue-type`	No	string-enum[] Task Queue type. If not specified, all types are reported. Accepted values: workflow, activity, nexus.
`--task-queue-type-legacy`	No	string-enum Task Queue type (legacy mode only). Accepted values: workflow, activity.	`workflow`

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.

Flag	Required	Description	Default
`--build-id`	No	string[] One or more Build ID strings. Can be passed multiple times.
`--reachability-type`	No	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.	`existing`
`--task-queue`, `-t`	No	string[] Search only the specified task queue(s). Can be passed multiple times.

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.

Flag	Required	Description	Default
`--max-sets`	No	int Max return count. Use 1 for default major version. Use 0 for all sets.	`0`
`--task-queue`, `-t`	Yes	string Task Queue 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.

Flag	Required	Description	Default
`--task-queue`, `-t`	Yes	string Task Queue 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.

Flag	Required	Description
`--build-id`	Yes	string Build ID to be added.
`--existing-compatible-build-id`	Yes	string Pre-existing Build ID in this Task Queue.
`--set-as-default`	No	bool Set the expanded Build ID set as the Task Queue default.
`--task-queue`, `-t`	Yes	string Task Queue 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.

Flag	Required	Description	Default
`--build-id`	Yes	string Build ID to be added.
`--task-queue`, `-t`	Yes	string Task Queue 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.

Flag	Required	Description	Default
`--build-id`	Yes	string Build ID to set as default.
`--task-queue`, `-t`	Yes	string Task Queue 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.

Flag	Required	Description	Default
`--build-id`	Yes	string Build ID within the promoted set.
`--task-queue`, `-t`	Yes	string Task Queue 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.

Flag	Required	Description
`--source-build-id`	Yes	string Source build ID.
`--target-build-id`	Yes	string Target build ID.
`--yes`, `-y`	No	bool Don't prompt to confirm.

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.

Flag	Required	Description
`--build-id`	Yes	string Target build ID.
`--force`	No	bool Bypass recent-poller validation.
`--yes`, `-y`	No	bool Don't prompt to confirm.

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.

Flag	Required	Description
`--force`	No	bool Bypass one-unconditional-rule validation.
`--rule-index`, `-i`	Yes	int Position of the assignment rule to be replaced. Requests for invalid indices will fail.
`--yes`, `-y`	No	bool Don't prompt to confirm.

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.

Flag	Required	Description	Default
`--source-build-id`	Yes	string Source Build ID.
`--yes`, `-y`	No	bool Don't prompt to confirm.

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.         |
+---------------------------------------------------------------------+

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.

Flag	Required	Description	Default
`--build-id`	Yes	string Target Build ID.
`--percentage`	No	int Traffic percent to send to target Build ID.	`100`
`--rule-index`, `-i`	No	int Insertion position. Ranges from 0 (insert at start) to count (append). Any number greater than the count is treated as "append".	`0`
`--yes`, `-y`	No	bool Don't prompt to confirm.

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.

Flag	Required	Description	Default
`--build-id`	Yes	string Target Build ID.
`--force`	No	bool Bypass the validation that one unconditional rule remains.
`--percentage`	No	int Divert percent of traffic to target Build ID.	`100`
`--rule-index`, `-i`	Yes	int Position of the assignment rule to be replaced. Requests for invalid indices will fail.
`--yes`, `-y`	No	bool Don't prompt to confirm.

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.

Flag	Required	Description
`--source-build-id`	Yes	string Source Build ID.
`--target-build-id`	Yes	string Target Build ID.
`--yes`, `-y`	No	bool Don't prompt to confirm.

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/temporal/temporal.toml` where `$CONFIG_PATH` is defined as `$HOME/.config` on Unix, `$HOME/Library/Application Support` on macOS, and `%AppData%` on Windows. (Experimental)
`--disable-config-env`	No	bool If set, disables loading environment config from environment variables. (Experimental)
`--disable-config-file`	No	bool If set, disables loading environment config from config file. (Experimental)
`--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 "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never.	`info`
`--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. (Experimental)
`--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.

config​

get​

set​

describe​

get-build-id-reachability​

get-build-ids​

list-partition​

update-build-ids​

add-new-compatible​

add-new-default​

promote-id-in-set​

promote-set​

versioning​

add-redirect-rule​

commit-build-id​

delete-assignment-rule​

delete-redirect-rule​

get-rules​

insert-assignment-rule​

replace-assignment-rule​

replace-redirect-rule​

Global Flags​

config

get

set

describe

get-build-id-reachability

get-build-ids

list-partition

update-build-ids

add-new-compatible

add-new-default

promote-id-in-set

promote-set

versioning

add-redirect-rule

commit-build-id

delete-assignment-rule

delete-redirect-rule

get-rules

insert-assignment-rule

replace-assignment-rule

replace-redirect-rule

Global Flags