# UI is now accessible from host at http://localhost:8233/
```

:::

### What the local server provides

- A local instance of the Temporal Service
- Automatic startup of the Web UI
- A default Namespace
- Optional persistence using SQLite

Omitting `--db-filename` uses an in-memory database. This speeds up testing but does not persist Workflow data between sessions.

### Access the Web UI

- Temporal Service: `localhost:7233`
- Web UI: [http://localhost:8233](http://localhost:8233)

:::tip
The CLI works with all Temporal SDKs.
Use it to develop and test your application before deploying to production.
:::

## Getting CLI help

From the command line:

```
temporal <command> <subcommand> --help
```

For example:

- `temporal --help`
- `temporal workflow --help`
- `temporal workflow delete --help`

Available commands

| Command                            | Description                                                 |
| ---------------------------------- | ----------------------------------------------------------- |
| [**activity**](/cli/activity)      | Complete, update, pause, unpause, reset or fail an Activity |
| [**batch**](/cli/batch)            | Manage running batch jobs                                   |
| [**completion**](/cli/cmd-options) | Generate the autocompletion script for the specified shell  |
| [**env**](/cli/env)                | Manage environments                                         |
| [**operator**](/cli/operator)      | Manage Temporal deployments                                 |
| [**schedule**](/cli/schedule)      | Perform operations on Schedules                             |
| [**server**](/cli/server)          | Run Temporal Server                                         |
| [**task-queue**](/cli/task-queue)  | Manage Task Queues                                          |
| [**worker**](/cli/worker)          | Read or update Worker state                                 |
| [**workflow**](/cli/workflow)      | Start, list, and operate on Workflows                       |

---

## Temporal CLI task-queue command reference

{/* 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/temporalcli/commandsgen/commands.yml */}
## 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.

**Flags:**

**--task-queue**, **-t** _string_

Task Queue name. Required.

**--task-queue-type** _string-enum_

Task Queue type. Accepted values: workflow, activity, nexus. Required. Accepted values: workflow, activity, nexus.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### set

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.

**Flags:**

**--fairness-key-rps-limit-default** _string_

Fairness key rate limit default in requests per second. Accepts a float; or 'default' to unset.

**--fairness-key-rps-limit-reason** _string_

Reason for fairness key rate limit update.

**--queue-rps-limit** _string_

Queue rate limit in requests per second. Accepts a float; or 'default' to unset.

**--queue-rps-limit-reason** _string_

Reason for queue rate limit update.

**--task-queue**, **-t** _string_

Task Queue name. Required.

**--task-queue-type** _string-enum_

Task Queue type. Accepted values: workflow, activity, nexus. Required. Accepted values: workflow, activity, nexus.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## describe

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

**Flags:**

**--disable-stats** _bool_

Disable task queue statistics.

**--legacy-mode** _bool_

Enable a legacy mode for servers that do not support rules-based worker versioning. This mode only provides pollers info.

**--partitions-legacy** _int_

Query partitions 1 through `N`. Experimental/Temporary feature. Legacy mode only. (default "1")

**--report-config** _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** _bool_

Display task reachability information.

**--select-all-active** _bool_

Include all active versions. A version is active if it had new tasks or polls recently.

**--select-build-id** _string[]_

Filter the Task Queue based on Build ID.

**--select-unversioned** _bool_

Include the unversioned queue.

**--task-queue**, **-t** _string_

Task Queue name. Required.

**--task-queue-type** _string-enum[]_

Task Queue type. If not specified, all types are reported. Accepted values: workflow, activity, nexus.

**--task-queue-type-legacy** _string-enum_

Task Queue type (legacy mode only). Accepted values: workflow, activity. (default "workflow")

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## get-build-id-reachability

```
+-----------------------------------------------------------------------------+
| CAUTION: This command is deprecated and will be removed in a later release. |
+-----------------------------------------------------------------------------+
```

Show if a given Build ID can be used for new, existing, or closed Workflows
in Namespaces that support Worker versioning:

```
temporal task-queue get-build-id-reachability \
    --task-queue YourTaskQueue \
    --build-id "YourBuildId"
```

You can specify the `--build-id` and `--task-queue` flags multiple times. If
`--task-queue` is omitted, the command checks Build ID reachability against
all Task Queues.

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

**Flags:**

**--build-id** _string[]_

One or more Build ID strings. Can be passed multiple times.

**--reachability-type** _string-enum_

Reachability filter. `open`: reachable by one or more open workflows. `closed`: reachable by one or more closed workflows. `existing`: reachable by either. New Workflow Executions reachable by a Build ID are always reported. Accepted values: open, closed, existing. (default "existing")

**--task-queue**, **-t** _string[]_

Search only the specified task queue(s). Can be passed multiple times.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## get-build-ids

```
+-----------------------------------------------------------------------------+
| CAUTION: This command is deprecated and will be removed in a later release. |
+-----------------------------------------------------------------------------+
```

Fetch sets of compatible Build IDs for specified Task Queues and display their
information:

```
temporal task-queue get-build-ids \
    --task-queue YourTaskQueue
```

This command is limited to Namespaces that support Worker versioning.

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

**Flags:**

**--max-sets** _int_

Max return count. Use 1 for default major version. Use 0 for all sets. (default "0")

**--task-queue**, **-t** _string_

Task Queue name. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## list-partition

Display a Task Queue's partition list with assigned matching nodes:

```
temporal task-queue list-partition \
    --task-queue YourTaskQueue
```

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

**Flags:**

**--task-queue**, **-t** _string_

Task Queue name. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## update-build-ids

```
+-----------------------------------------------------------------------------+
| CAUTION: This command is deprecated and will be removed in a later release. |
+-----------------------------------------------------------------------------+
```

Add or change a Task Queue's compatible Build IDs for Namespaces using Worker
versioning:

```
temporal task-queue update-build-ids [subcommands] [options] \
    --task-queue YourTaskQueue
```

### add-new-compatible

Add a compatible Build ID to a Task Queue's existing version set. Provide an
existing Build ID and a new Build ID:

```
temporal task-queue update-build-ids add-new-compatible \
    --task-queue YourTaskQueue \
    --existing-compatible-build-id "YourExistingBuildId" \
    --build-id "YourNewBuildId"
```

The new ID is stored in the set containing the existing ID and becomes the new
default for that set.

This command is limited to Namespaces that support Worker versioning.

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

**Flags:**

**--build-id** _string_

Build ID to be added. Required.

**--existing-compatible-build-id** _string_

Pre-existing Build ID in this Task Queue. Required.

**--set-as-default** _bool_

Set the expanded Build ID set as the Task Queue default.

**--task-queue**, **-t** _string_

Task Queue name. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### add-new-default

```
+-----------------------------------------------------------------------------+
| CAUTION: This command is deprecated and will be removed in a later release. |
+-----------------------------------------------------------------------------+
```

Create a new Task Queue Build ID set, add a Build ID to it, and make it the
overall Task Queue default. The new set will be incompatible with previous
sets and versions.

```
temporal task-queue update-build-ids add-new-default \
    --task-queue YourTaskQueue \
    --build-id "YourNewBuildId"
```

```
+------------------------------------------------------------------------+
| NOTICE: This command is limited to Namespaces that support Worker      |
| versioning. Worker versioning is experimental. Versioning commands are |
| subject to change.                                                     |
+------------------------------------------------------------------------+
```

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

**Flags:**

**--build-id** _string_

Build ID to be added. Required.

**--task-queue**, **-t** _string_

Task Queue name. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### promote-id-in-set

```
+-----------------------------------------------------------------------------+
| CAUTION: This command is deprecated and will be removed in a later release. |
+-----------------------------------------------------------------------------+
```

Establish an existing Build ID as the default in its Task Queue set. New tasks
compatible with this set will now be dispatched to this ID:

```
temporal task-queue update-build-ids promote-id-in-set \
    --task-queue YourTaskQueue \
    --build-id "YourBuildId"
```

```
+------------------------------------------------------------------------+
| NOTICE: This command is limited to Namespaces that support Worker      |
| versioning. Worker versioning is experimental. Versioning commands are |
| subject to change.                                                     |
+------------------------------------------------------------------------+
```

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

**Flags:**

**--build-id** _string_

Build ID to set as default. Required.

**--task-queue**, **-t** _string_

Task Queue name. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### promote-set

```
+-----------------------------------------------------------------------------+
| CAUTION: This command is deprecated and will be removed in a later release. |
+-----------------------------------------------------------------------------+
```

Promote a Build ID set to be the default on a Task Queue. Identify the set by
providing a Build ID within it. If the set is already the default, this
command has no effect:

```
temporal task-queue update-build-ids promote-set \
    --task-queue YourTaskQueue \
    --build-id "YourBuildId"
```

```
+------------------------------------------------------------------------+
| NOTICE: This command is limited to Namespaces that support Worker      |
| versioning. Worker versioning is experimental. Versioning commands are |
| subject to change.                                                     |
+------------------------------------------------------------------------+
```

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

**Flags:**

**--build-id** _string_

Build ID within the promoted set. Required.

**--task-queue**, **-t** _string_

Task Queue name. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## versioning

```
+---------------------------------------------------------------------+
| CAUTION: This API has been deprecated by Worker Deployment.         |
+---------------------------------------------------------------------+
```

Provides commands to add, list, remove, or replace Worker Build ID assignment
and redirect rules associated with Task Queues:

```
temporal task-queue versioning [subcommands] [options] \
    --task-queue YourTaskQueue
```

Task Queues support the following versioning rules and policies:

- Assignment Rules: manage how new executions are assigned to run on specific
  Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,
  which are evaluated from first to last. Assignment Rules also allow for
  gradual rollout of new Build IDs by setting ramp percentage.
- Redirect Rules: automatically assign work for a source Build ID to a target
  Build ID. You may add at most one redirect rule for each source Build ID.
  Redirect rules require that a target Build ID is fully compatible with
  the source Build ID.

### add-redirect-rule

Add a new redirect rule for a given Task Queue. You may add at most one
redirect rule for each distinct source build ID:

```
temporal task-queue versioning add-redirect-rule \
    --task-queue YourTaskQueue \
    --source-build-id "YourSourceBuildID" \
    --target-build-id "YourTargetBuildID"
```

```
+---------------------------------------------------------------------+
| CAUTION: This API has been deprecated by Worker Deployment.         |
+---------------------------------------------------------------------+
```

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

**Flags:**

**--source-build-id** _string_

Source build ID. Required.

**--target-build-id** _string_

Target build ID. Required.

**--yes**, **-y** _bool_

Don't prompt to confirm.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### commit-build-id

Complete a Build ID's rollout and clean up unnecessary rules that might have
been created during a gradual rollout:

```
temporal task-queue versioning commit-build-id \
    --task-queue YourTaskQueue
    --build-id "YourBuildId"
```

This command automatically applies the following atomic changes:

- Adds an unconditional assignment rule for the target Build ID at the
  end of the list.
- Removes all previously added assignment rules to the given target
  Build ID.
- Removes any unconditional assignment rules for other Build IDs.

Rejects requests when there have been no recent pollers for this Build ID.
This prevents committing invalid Build IDs. Use the `--force` option to
override this validation.

```
+---------------------------------------------------------------------+
| CAUTION: This API has been deprecated by Worker Deployment.         |
+---------------------------------------------------------------------+
```

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

**Flags:**

**--build-id** _string_

Target build ID. Required.

**--force** _bool_

Bypass recent-poller validation.

**--yes**, **-y** _bool_

Don't prompt to confirm.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### delete-assignment-rule

Deletes a rule identified by its index in the Task Queue's list of assignment
rules.

```
temporal task-queue versioning delete-assignment-rule \
    --task-queue YourTaskQueue \
    --rule-index YourIntegerRuleIndex
```

By default, the Task Queue must retain one unconditional rule, such as "no
hint filter" or "percentage". Otherwise, the delete operation is rejected.
Use the `--force` option to override this validation.

```
+---------------------------------------------------------------------+
| CAUTION: This API has been deprecated by Worker Deployment.         |
+---------------------------------------------------------------------+
```

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

**Flags:**

**--force** _bool_

Bypass one-unconditional-rule validation.

**--rule-index**, **-i** _int_

Position of the assignment rule to be replaced. Requests for invalid indices will fail. Required.

**--yes**, **-y** _bool_

Don't prompt to confirm.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### delete-redirect-rule

Deletes the routing rule for the given source Build ID.

```
temporal task-queue versioning delete-redirect-rule \
    --task-queue YourTaskQueue \
    --source-build-id "YourBuildId"
```

```
+---------------------------------------------------------------------+
| CAUTION: This API has been deprecated by Worker Deployment.         |
+---------------------------------------------------------------------+
```

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

**Flags:**

**--source-build-id** _string_

Source Build ID. Required.

**--yes**, **-y** _bool_

Don't prompt to confirm.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### get-rules

Retrieve all the Worker Build ID assignments and redirect rules associated
with a Task Queue:

```
temporal task-queue versioning get-rules \
    --task-queue YourTaskQueue
```

Task Queues support the following versioning rules:

- Assignment Rules: manage how new executions are assigned to run on specific
  Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,
  which are evaluated from first to last. Assignment Rules also allow for
  gradual rollout of new Build IDs by setting ramp percentage.
- Redirect Rules: automatically assign work for a source Build ID to a target
  Build ID. You may add at most one redirect rule for each source Build ID.
  Redirect rules require that a target Build ID is fully compatible with
  the source Build ID.
```
+---------------------------------------------------------------------+
| CAUTION: This API has been deprecated by Worker Deployment.         |
+---------------------------------------------------------------------+
```

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

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### insert-assignment-rule

Inserts a new assignment rule for this Task Queue. Rules are evaluated in
order, starting from index 0. The first applicable rule is applied, and the
rest ignored:

```
temporal task-queue versioning insert-assignment-rule \
    --task-queue YourTaskQueue \
    --build-id "YourBuildId"
```

If you do not specify a `--rule-index`, this command inserts at index 0.

```
+---------------------------------------------------------------------+
| CAUTION: This API has been deprecated by Worker Deployment.         |
+---------------------------------------------------------------------+
```

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

**Flags:**

**--build-id** _string_

Target Build ID. Required.

**--percentage** _int_

Traffic percent to send to target Build ID. (default "100")

**--rule-index**, **-i** _int_

Insertion position. Ranges from 0 (insert at start) to count (append). Any number greater than the count is treated as "append". (default "0")

**--yes**, **-y** _bool_

Don't prompt to confirm.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### replace-assignment-rule

Change an assignment rule for this Task Queue. By default, this enforces one
unconditional rule (no hint filter or percentage). Otherwise, the operation
will be rejected. Set `force` to true to bypass this validation.

```
temporal task-queue versioning replace-assignment-rule \
    --task-queue YourTaskQueue \
    --rule-index AnIntegerIndex \
    --build-id "YourBuildId"
```

To assign multiple assignment rules to a single Build ID, use
'insert-assignment-rule'.

To update the percent:

```
temporal task-queue versioning replace-assignment-rule \
    --task-queue YourTaskQueue \
    --rule-index AnIntegerIndex \
    --build-id "YourBuildId" \
    --percentage AnIntegerPercent
```

Percent may vary between 0 and 100 (default).

```
+---------------------------------------------------------------------+
| CAUTION: This API has been deprecated by Worker Deployment.         |
+---------------------------------------------------------------------+
```

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

**Flags:**

**--build-id** _string_

Target Build ID. Required.

**--force** _bool_

Bypass the validation that one unconditional rule remains.

**--percentage** _int_

Divert percent of traffic to target Build ID. (default "100")

**--rule-index**, **-i** _int_

Position of the assignment rule to be replaced. Requests for invalid indices will fail. Required.

**--yes**, **-y** _bool_

Don't prompt to confirm.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### replace-redirect-rule

Updates a Build ID's redirect rule on a Task Queue by replacing its target
Build ID:

```
temporal task-queue versioning replace-redirect-rule \
    --task-queue YourTaskQueue \
    --source-build-id YourSourceBuildId \
    --target-build-id YourNewTargetBuildId
```

```
+---------------------------------------------------------------------+
| CAUTION: This API has been deprecated by Worker Deployment.         |
+---------------------------------------------------------------------+
```

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

**Flags:**

**--source-build-id** _string_

Source Build ID. Required.

**--target-build-id** _string_

Target Build ID. Required.

**--yes**, **-y** _bool_

Don't prompt to confirm.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

---

## Temporal CLI worker command reference

{/* 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/temporalcli/commandsgen/commands.yml */}
## deployment

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

Deployment commands perform operations on Worker Deployments:

```
temporal worker deployment [command] [options]
```

For example:

```
temporal worker deployment list
```

Lists the Deployments in the client's namespace.

Arguments can be Worker Deployment Versions associated with
a Deployment, specified using the Deployment name and Build ID.

For example:

```
temporal worker deployment set-current-version \
         --deployment-name YourDeploymentName --build-id YourBuildID
```

Sets the current Deployment Version for a given Deployment.

### delete

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

Remove a Worker Deployment given its Deployment Name.
A Deployment can only be deleted if it has no Version in it.

```
temporal worker deployment delete [options]
```

For example, setting the user identity that removed the deployment:

```
temporal worker deployment delete \
    --name YourDeploymentName \
    --identity YourIdentity

```

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

**Flags:**

**--name**, **-d** _string_

Name for a Worker Deployment. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### delete-version

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

Remove a Worker Deployment Version given its fully-qualified identifier.
This is rarely needed during normal operation
since unused Versions are eventually garbage collected.
The client can delete a Version only when all of the following conditions
are met:
  - It is not the Current or Ramping Version for this Deployment.
  - It has no active pollers, i.e., none of the task queues in the
  Version have pollers.
  - It is not draining. This requirement can be ignored with the option
`--skip-drainage`.
```
temporal worker deployment delete-version [options]
```

For example, skipping the drainage restriction:

```
temporal worker deployment delete-version \
    --deployment-name YourDeploymentName --build-id YourBuildID \
    --skip-drainage
```

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

**Flags:**

**--build-id** _string_

Build ID of the Worker Deployment Version. Required.

**--deployment-name** _string_

Name of the Worker Deployment. Required.

**--skip-drainage** _bool_

Ignore the deletion requirement of not draining.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### describe

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

Describe properties of a Worker Deployment, such as the versions
associated with it, routing information of new or existing tasks
executed by this deployment, or its creation time.

```
temporal worker deployment describe [options]
```

For example, to describe a deployment `YourDeploymentName` in the default
namespace:

```
temporal worker deployment describe \
    --name YourDeploymentName
```

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

**Flags:**

**--name**, **-d** _string_

Name for a Worker Deployment. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### describe-version

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

Describe properties of a Worker Deployment Version, such as the task
queues polled by workers in this Deployment Version, or drainage
information required to safely decommission workers, or user-provided
metadata, or its creation/modification time.

```
temporal worker deployment describe-version [options]
```

For example, to describe a deployment version  in a deployment
`YourDeploymentName`, with Build ID `YourBuildID`, and in the default
namespace:

```
temporal worker deployment describe-version \
    --deployment-name YourDeploymentName --build-id YourBuildID
```

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

**Flags:**

**--build-id** _string_

Build ID of the Worker Deployment Version. Required.

**--deployment-name** _string_

Name of the Worker Deployment. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### list

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

List existing Worker Deployments in the client's namespace.

```
temporal worker deployment list [options]
```

For example, listing Deployments in YourDeploymentNamespace:

```
temporal worker deployment list \
    --namespace YourDeploymentNamespace
```

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

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### manager-identity

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

Manager Identity commands change the `ManagerIdentity` of a Worker Deployment:

```
temporal worker deployment manager-identity [command] [options]
```

When present, `ManagerIdentity` is the identity of the user that has the 
exclusive right to make changes to this Worker Deployment. Empty by default.
When set, users whose identity does not match the `ManagerIdentity` will not
be able to change the Worker Deployment.

This is especially useful in environments where multiple users (such as CLI
users and automated controllers) may interact with the same Worker Deployment.
`ManagerIdentity` allows different users to communicate with one another about
who is expected to make changes to the Worker Deployment.

The current Manager Identity is returned with `describe`:
```
 temporal worker deployment describe \
    --deployment-name YourDeploymentName
```

#### set

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

Set the `ManagerIdentity` of a Worker Deployment given its Deployment Name.

When present, `ManagerIdentity` is the identity of the user that has the 
exclusive right to make changes to this Worker Deployment. Empty by default.
When set, users whose identity does not match the `ManagerIdentity` will not
be able to change the Worker Deployment.

This is especially useful in environments where multiple users (such as CLI
users and automated controllers) may interact with the same Worker Deployment.
`ManagerIdentity` allows different users to communicate with one another about
who is expected to make changes to the Worker Deployment.

```
temporal worker deployment manager-identity set [options]
```

For example:

```
temporal worker deployment manager-identity set \
   --deployment-name DeploymentName \
   --self \
   --identity YourUserIdentity # optional, populated by CLI if not provided
```

Sets the Manager Identity of the Deployment to the identity of the user making 
this request. If you don't specifically pass an identity field, the CLI will 
generate your identity for you.

For example:
```
temporal worker deployment manager-identity set \
   --deployment-name DeploymentName \
   --manager-identity NewManagerIdentity
```

Sets the Manager Identity of the Deployment to any string.

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

**Flags:**

**--deployment-name** _string_

Name for a Worker Deployment. Required.

**--manager-identity** _string_

New Manager Identity. Required unless --self is specified.

**--self** _bool_

Set Manager Identity to the identity of the user submitting this request. Required unless --manager-identity is specified.

**--yes**, **-y** _bool_

Don't prompt to confirm set Manager Identity.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

#### unset

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

Unset the `ManagerIdentity` of a Worker Deployment given its Deployment Name.

When present, `ManagerIdentity` is the identity of the user that has the 
exclusive right to make changes to this Worker Deployment. Empty by default.
When set, users whose identity does not match the `ManagerIdentity` will not
be able to change the Worker Deployment.

This is especially useful in environments where multiple users (such as CLI
users and automated controllers) may interact with the same Worker Deployment.
`ManagerIdentity` allows different users to communicate with one another about
who is expected to make changes to the Worker Deployment.

```
temporal worker deployment manager-identity unset [options]
```

For example:

```
temporal worker deployment manager-identity unset \
   --deployment-name YourDeploymentName
```

Clears the Manager Identity field for a given Deployment.

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

**Flags:**

**--deployment-name** _string_

Name for a Worker Deployment. Required.

**--yes**, **-y** _bool_

Don't prompt to confirm unset Manager Identity.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### set-current-version

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

Set the Current Version for a Deployment.
When a Version is current, Workers of that Deployment Version will receive
tasks from new Workflows, and from existing AutoUpgrade Workflows that
are running on this Deployment.

If not all the expected Task Queues are being polled by Workers in the
new Version the request will fail. To override this protection use
`--ignore-missing-task-queues`. Note that this would ignore task queues
in a deployment that are not yet discovered, leading to inconsistent task
queue configuration.

```
temporal worker deployment set-current-version [options]
```

For example, to set the Current Version of a deployment
`YourDeploymentName`, with a version with Build ID `YourBuildID`, and
in the default namespace:

```
temporal worker deployment set-current-version \
    --deployment-name YourDeploymentName --build-id YourBuildID
```

The target of set-current-version can also be unversioned workers:

```
temporal worker deployment set-current-version \
    --deployment-name YourDeploymentName --unversioned
```

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

**Flags:**

**--allow-no-pollers** _bool_

Override protection and set version as current even if it has no pollers.

**--build-id** _string_

Build ID of the Worker Deployment Version. Required unless --unversioned is specified.

**--deployment-name** _string_

Name of the Worker Deployment. Required.

**--ignore-missing-task-queues** _bool_

Override protection to accidentally remove task queues.

**--unversioned** _bool_

Set unversioned workers as the target version. Cannot be used with --build-id.

**--yes**, **-y** _bool_

Don't prompt to confirm set Current Version.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### set-ramping-version

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

Set the Ramping Version and Percentage for a Deployment.

The Ramping Version can be set using deployment name and build ID,
or set to unversioned workers using the --unversioned flag.

The Ramping Percentage is a float with values in the range [0, 100].
A value of 100 does not make the Ramping Version Current, use
`set-current-version` instead.

To remove a Ramping Version use the flag `--delete`.

If not all the expected Task Queues are being polled by Workers in the
new Ramping Version the request will fail. To override this protection use
`--ignore-missing-task-queues`. Note that this would ignore task queues
in a deployment that are not yet discovered, leading to inconsistent task
queue configuration.

```
temporal worker deployment set-ramping-version [options]
```

For example, to set the Ramping Version of a deployment
`YourDeploymentName`, with a version with Build ID `YourBuildID`, with
10 percent of tasks redirected to this version, and
using the default namespace:

```
temporal worker deployment set-ramping-version \
    --deployment-name YourDeploymentName --build-id YourBuildID \
    --percentage 10.0
```

And to remove that ramping:
```
temporal worker deployment set-ramping-version \
    --deployment-name YourDeploymentName --build-id YourBuildID \
    --delete
```

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

**Flags:**

**--allow-no-pollers** _bool_

Override protection and set version as ramping even if it has no pollers.

**--build-id** _string_

Build ID of the Worker Deployment Version. Required unless --unversioned is specified.

**--delete** _bool_

Delete the Ramping Version.

**--deployment-name** _string_

Name of the Worker Deployment. Required.

**--ignore-missing-task-queues** _bool_

Override protection to accidentally remove task queues.

**--percentage** _float_

Percentage of tasks redirected to the Ramping Version. Valid range [0,100].

**--unversioned** _bool_

Set unversioned workers as the target version. Cannot be used with --build-id.

**--yes**, **-y** _bool_

Don't prompt to confirm set Ramping Version.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### update-metadata-version

```
+---------------------------------------------------------------------+
| CAUTION: Worker Deployment is experimental. Deployment commands are |
| subject to change.                                                  |
+---------------------------------------------------------------------+
```

Update metadata associated with a Worker Deployment Version.

For example:

```
 temporal worker deployment update-metadata-version \
    --deployment-name YourDeploymentName --build-id YourBuildID \
    --metadata bar=1 \
    --metadata foo=true
```

The current metadata is also returned with `describe-version`:
```
 temporal worker deployment describe-version \
    --deployment-name YourDeploymentName --build-id YourBuildID \
```

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

**Flags:**

**--build-id** _string_

Build ID of the Worker Deployment Version. Required.

**--deployment-name** _string_

Name of the Worker Deployment. Required.

**--metadata** _string[]_

Set deployment metadata using `KEY="VALUE"` pairs. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times.

**--remove-entries** _string[]_

Keys of entries to be deleted from metadata. Can be passed multiple times.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## describe

Look up information of a specific worker.

```
temporal worker describe --namespace YourNamespace --worker-instance-key YourKey
```

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

**Flags:**

**--worker-instance-key** _string_

Worker instance key to describe. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## list

Get a list of workers to the specified namespace.

```
temporal worker list --namespace YourNamespace --query 'taskQueue="YourTaskQueue"'
```

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

**Flags:**

**--limit** _int_

Maximum number of workers to display.

**--query**, **-q** _string_

Content for an SQL-like `QUERY` List Filter.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

---

## Temporal CLI workflow command reference

{/* 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/temporalcli/commandsgen/commands.yml */}
## cancel

Canceling a running Workflow Execution records a
`WorkflowExecutionCancelRequested` event in the Event History. The Service
schedules a new Command Task, and the Workflow Execution performs any cleanup
work supported by its implementation.

Use the Workflow ID to cancel an Execution:

```
temporal workflow cancel \
    --workflow-id YourWorkflowId
```

A visibility Query lets you send bulk cancellations to Workflow Executions
matching the results:

```
temporal workflow cancel \
    --query YourQuery
```

Visit https://docs.temporal.io/visibility to read more about Search Attributes
and Query creation. See `temporal batch --help` for a quick reference.

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

**Flags:**

**--query**, **-q** _string_

Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query.

**--reason** _string_

Reason for batch operation. Only use with --query. Defaults to user name.

**--rps** _float_

Limit batch's requests per second. Only allowed if query is present.

**--run-id**, **-r** _string_

Run ID. Only use with --workflow-id. Cannot use with --query.

**--workflow-id**, **-w** _string_

Workflow ID. You must set either --workflow-id or --query.

**--yes**, **-y** _bool_

Don't prompt to confirm signaling. Only allowed when --query is present.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## count

Show a count of Workflow Executions, regardless of execution state (running,
terminated, etc). Use `--query` to select a subset of Workflow Executions:

```
temporal workflow count \
    --query YourQuery
```

Visit https://docs.temporal.io/visibility to read more about Search Attributes
and Query creation. See `temporal batch --help` for a quick reference.

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

**Flags:**

**--query**, **-q** _string_

Content for an SQL-like `QUERY` List Filter.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## delete

Delete a Workflow Executions and its Event History:

```
temporal workflow delete \
    --workflow-id YourWorkflowId
```

The removal executes asynchronously. If the Execution is Running, the Service
terminates it before deletion.

Visit https://docs.temporal.io/visibility to read more about Search Attributes
and Query creation. See `temporal batch --help` for a quick reference.

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

**Flags:**

**--query**, **-q** _string_

Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query.

**--reason** _string_

Reason for batch operation. Only use with --query. Defaults to user name.

**--rps** _float_

Limit batch's requests per second. Only allowed if query is present.

**--run-id**, **-r** _string_

Run ID. Only use with --workflow-id. Cannot use with --query.

**--workflow-id**, **-w** _string_

Workflow ID. You must set either --workflow-id or --query.

**--yes**, **-y** _bool_

Don't prompt to confirm signaling. Only allowed when --query is present.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## describe

Display information about a specific Workflow Execution:

```
temporal workflow describe \
    --workflow-id YourWorkflowId
```

Show the Workflow Execution's auto-reset points:

```
temporal workflow describe \
    --workflow-id YourWorkflowId \
    --reset-points true
```

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

**Flags:**

**--raw** _bool_

Print properties without changing their format.

**--reset-points** _bool_

Show auto-reset points only.

**--run-id**, **-r** _string_

Run ID.

**--workflow-id**, **-w** _string_

Workflow ID. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## execute

Establish a new Workflow Execution and direct its progress to stdout. The
command blocks and returns when the Workflow Execution completes. If your
Workflow requires input, pass valid JSON:

```
temporal workflow execute
    --workflow-id YourWorkflowId \
    --type YourWorkflow \
    --task-queue YourTaskQueue \
    --input '{"some-key": "some-value"}'
```

Use `--event-details` to relay updates to the command-line output in JSON
format. When using JSON output (`--output json`), this includes the entire
"history" JSON key for the run.

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

**Flags:**

**--cron** _string_

Cron schedule for the Workflow.

**--detailed** _bool_

Display events as sections instead of table. Does not apply to JSON output.

**--execution-timeout** _duration_

Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks.

**--fail-existing** _bool_

Fail if the Workflow already exists.

**--fairness-key** _string_

Fairness key (max 64 bytes) for proportional task dispatch. Tasks with same key share capacity based on their weight.

**--fairness-weight** _float_

Weight [0.001-1000] for this fairness key. Keys are dispatched proportionally to their weights.

**--id-conflict-policy** _string-enum_

Determines how to resolve a conflict when spawning a new Workflow Execution with a particular Workflow Id used by an existing Open Workflow Execution. Accepted values: Fail, UseExisting, TerminateExisting.

**--id-reuse-policy** _string-enum_

Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning.

**--input**, **-i** _string[]_

Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.

**--input-base64** _bool_

Assume inputs are base64-encoded and attempt to decode them.

**--input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.

**--input-meta** _string[]_

Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. Repeated metadata keys are applied to the corresponding inputs in the provided order.

**--memo** _string[]_

Memo using 'KEY="VALUE"' pairs. Use JSON values.

**--priority-key** _int_

Priority key (1-5, lower numbers = higher priority). Tasks in a queue should be processed in close-to-priority-order. Default is 3 when not specified.

**--run-timeout** _duration_

Fail a Workflow Run if it lasts longer than `DURATION`.

**--search-attribute** _string[]_

Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times.

**--start-delay** _duration_

Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately.

**--static-details** _string_

Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines.

:::note

Option is experimental.

:::

**--static-summary** _string_

Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line.

:::note

Option is experimental.

:::

**--task-queue**, **-t** _string_

Workflow Task queue. Required.

**--task-timeout** _duration_

Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s")

**--type** _string_

Workflow Type name. Required.

**--workflow-id**, **-w** _string_

Workflow ID. If not supplied, the Service generates a unique ID.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## execute-update-with-start

Send a message to a Workflow Execution to invoke an Update handler, and wait for
the update to complete. If the Workflow Execution is not running, then a new workflow
execution is started and the update is sent.

Experimental.

```
temporal workflow execute-update-with-start \
  --update-name YourUpdate \
  --update-input '{"update-key": "update-value"}' \
  --workflow-id YourWorkflowId \
  --type YourWorkflowType \
  --task-queue YourTaskQueue \
  --id-conflict-policy Fail \
  --input '{"wf-key": "wf-value"}'
```

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

**Flags:**

**--cron** _string_

Cron schedule for the Workflow.

**--execution-timeout** _duration_

Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks.

**--fail-existing** _bool_

Fail if the Workflow already exists.

**--fairness-key** _string_

Fairness key (max 64 bytes) for proportional task dispatch. Tasks with same key share capacity based on their weight.

**--fairness-weight** _float_

Weight [0.001-1000] for this fairness key. Keys are dispatched proportionally to their weights.

**--id-conflict-policy** _string-enum_

Determines how to resolve a conflict when spawning a new Workflow Execution with a particular Workflow Id used by an existing Open Workflow Execution. Accepted values: Fail, UseExisting, TerminateExisting.

**--id-reuse-policy** _string-enum_

Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning.

**--input**, **-i** _string[]_

Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.

**--input-base64** _bool_

Assume inputs are base64-encoded and attempt to decode them.

**--input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.

**--input-meta** _string[]_

Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. Repeated metadata keys are applied to the corresponding inputs in the provided order.

**--memo** _string[]_

Memo using 'KEY="VALUE"' pairs. Use JSON values.

**--priority-key** _int_

Priority key (1-5, lower numbers = higher priority). Tasks in a queue should be processed in close-to-priority-order. Default is 3 when not specified.

**--run-id**, **-r** _string_

Run ID. If unset, looks for an Update against the currently-running Workflow Execution.

**--run-timeout** _duration_

Fail a Workflow Run if it lasts longer than `DURATION`.

**--search-attribute** _string[]_

Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times.

**--start-delay** _duration_

Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately.

**--static-details** _string_

Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines.

:::note

Option is experimental.

:::

**--static-summary** _string_

Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line.

:::note

Option is experimental.

:::

**--task-queue**, **-t** _string_

Workflow Task queue. Required.

**--task-timeout** _duration_

Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s")

**--type** _string_

Workflow Type name. Required.

**--update-first-execution-run-id** _string_

Parent Run ID. The update is sent to the last Workflow Execution in the chain started with this Run ID.

**--update-id** _string_

Update ID. If unset, defaults to a UUID.

**--update-input** _string[]_

Update input value. Use JSON content or set --update-input-meta to override. Can't be combined with --update-input-file. Can be passed multiple times to pass multiple arguments.

**--update-input-base64** _bool_

Assume update inputs are base64-encoded and attempt to decode them.

**--update-input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --update-input-meta to override. Can't be combined with --update-input. Can be passed multiple times to pass multiple arguments.

**--update-input-meta** _string[]_

Input update payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times.

**--update-name** _string_

Update name. Required.

**--workflow-id**, **-w** _string_

Workflow ID. If not supplied, the Service generates a unique ID.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## fix-history-json

Reserialize an Event History JSON file:

```
temporal workflow fix-history-json \
    --source /path/to/original.json \
    --target /path/to/reserialized.json
```

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

**Flags:**

**--source**, **-s** _string_

Path to the original file. Required.

**--target**, **-t** _string_

Path to the results file. When omitted, output is sent to stdout.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## list

List Workflow Executions. The optional `--query` limits the output to
Workflows matching a Query:

```
temporal workflow list \
    --query YourQuery`
```

Visit https://docs.temporal.io/visibility to read more about Search Attributes
and Query creation. See `temporal batch --help` for a quick reference.

View a list of archived Workflow Executions:

```
temporal workflow list \
    --archived
```

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

**Flags:**

**--archived** _bool_

Limit output to archived Workflow Executions.

:::note

Option is experimental.

:::

**--limit** _int_

Maximum number of Workflow Executions to display.

**--page-size** _int_

Maximum number of Workflow Executions to fetch at a time from the server.

**--query**, **-q** _string_

Content for an SQL-like `QUERY` List Filter.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## metadata

Issue a Query for and display user-set metadata like summary and
details for a specific Workflow Execution:

```
temporal workflow metadata \
    --workflow-id YourWorkflowId
```

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

**Flags:**

**--reject-condition** _string-enum_

Optional flag for rejecting Queries based on Workflow state. Accepted values: not_open, not_completed_cleanly.

**--run-id**, **-r** _string_

Run ID.

**--workflow-id**, **-w** _string_

Workflow ID. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## query

Send a Query to a Workflow Execution by Workflow ID to retrieve its state.
This synchronous operation exposes the internal state of a running Workflow
Execution, which constantly changes. You can query both running and completed
Workflow Executions:

```
temporal workflow query \
    --workflow-id YourWorkflowId
    --type YourQueryType
    --input '{"YourInputKey": "YourInputValue"}'
```

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

**Flags:**

**--input**, **-i** _string[]_

Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.

**--input-base64** _bool_

Assume inputs are base64-encoded and attempt to decode them.

**--input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.

**--input-meta** _string[]_

Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. Repeated metadata keys are applied to the corresponding inputs in the provided order.

**--name** _string_

Query Type/Name. Required.

**--reject-condition** _string-enum_

Optional flag for rejecting Queries based on Workflow state. Accepted values: not_open, not_completed_cleanly.

**--run-id**, **-r** _string_

Run ID.

**--workflow-id**, **-w** _string_

Workflow ID. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## reset

Reset a Workflow Execution so it can resume from a point in its Event History
without losing its progress up to that point:

```
temporal workflow reset \
    --workflow-id YourWorkflowId \
    --event-id YourLastEvent
```

Start from where the Workflow Execution last continued as new:

```
temporal workflow reset \
    --workflow-id YourWorkflowId \
    --type LastContinuedAsNew
```

For batch resets, limit your resets to FirstWorkflowTask, LastWorkflowTask, or
BuildId. Do not use Workflow IDs, run IDs, or event IDs with this command.

Visit https://docs.temporal.io/visibility to read more about Search
Attributes and Query creation.

### with-workflow-update-options

Run Workflow Update Options atomically after the Workflow is reset.
Workflows selected by the reset command are forwarded onto the subcommand.

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

**Flags:**

**--versioning-override-behavior** _string-enum_

Override the versioning behavior of a Workflow. Required. Accepted values: pinned, auto_upgrade.

**--versioning-override-build-id** _string_

When overriding to a `pinned` behavior, specifies the Build ID of the version to target.

**--versioning-override-deployment-name** _string_

When overriding to a `pinned` behavior, specifies the Deployment Name of the version to target.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## result

Wait for and print the result of a Workflow Execution:

```
temporal workflow result \
    --workflow-id YourWorkflowId
```

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

**Flags:**

**--run-id**, **-r** _string_

Run ID.

**--workflow-id**, **-w** _string_

Workflow ID. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## show

Show a Workflow Execution's Event History.
When using JSON output (`--output json`), you may pass the results to an SDK
to perform a replay:

```
temporal workflow show \
    --workflow-id YourWorkflowId
    --output json
```

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

**Flags:**

**--detailed** _bool_

Display events as detailed sections instead of table. Does not apply to JSON output.

**--follow**, **-f** _bool_

Follow the Workflow Execution progress in real time. Does not apply to JSON output.

**--run-id**, **-r** _string_

Run ID.

**--workflow-id**, **-w** _string_

Workflow ID. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## signal

Send an asynchronous notification (Signal) to a running Workflow Execution by
its Workflow ID. The Signal is written to the History. When you include
`--input`, that data is available for the Workflow Execution to consume:

```
temporal workflow signal \
    --workflow-id YourWorkflowId \
    --name YourSignal \
    --input '{"YourInputKey": "YourInputValue"}'
```

Visit https://docs.temporal.io/visibility to read more about Search Attributes
and Query creation. See `temporal batch --help` for a quick reference.

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

**Flags:**

**--input**, **-i** _string[]_

Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.

**--input-base64** _bool_

Assume inputs are base64-encoded and attempt to decode them.

**--input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.

**--input-meta** _string[]_

Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. Repeated metadata keys are applied to the corresponding inputs in the provided order.

**--name** _string_

Signal name. Required.

**--query**, **-q** _string_

Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query.

**--reason** _string_

Reason for batch operation. Only use with --query. Defaults to user name.

**--rps** _float_

Limit batch's requests per second. Only allowed if query is present.

**--run-id**, **-r** _string_

Run ID. Only use with --workflow-id. Cannot use with --query.

**--workflow-id**, **-w** _string_

Workflow ID. You must set either --workflow-id or --query.

**--yes**, **-y** _bool_

Don't prompt to confirm signaling. Only allowed when --query is present.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## signal-with-start

Send an asynchronous notification (Signal) to a Workflow Execution.
If the Workflow Execution is not running or is not found, it starts the
workflow then sends the signal.

```
temporal workflow signal-with-start \
  --signal-name YourSignal \
  --signal-input '{"some-key": "some-value"}' \
  --workflow-id YourWorkflowId \
  --type YourWorkflowType \
  --task-queue YourTaskQueue \
  --input '{"some-key": "some-value"}'
```

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

**Flags:**

**--cron** _string_

Cron schedule for the Workflow.

**--execution-timeout** _duration_

Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks.

**--fail-existing** _bool_

Fail if the Workflow already exists.

**--fairness-key** _string_

Fairness key (max 64 bytes) for proportional task dispatch. Tasks with same key share capacity based on their weight.

**--fairness-weight** _float_

Weight [0.001-1000] for this fairness key. Keys are dispatched proportionally to their weights.

**--id-conflict-policy** _string-enum_

Determines how to resolve a conflict when spawning a new Workflow Execution with a particular Workflow Id used by an existing Open Workflow Execution. Accepted values: Fail, UseExisting, TerminateExisting.

**--id-reuse-policy** _string-enum_

Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning.

**--input**, **-i** _string[]_

Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.

**--input-base64** _bool_

Assume inputs are base64-encoded and attempt to decode them.

**--input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.

**--input-meta** _string[]_

Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. Repeated metadata keys are applied to the corresponding inputs in the provided order.

**--memo** _string[]_

Memo using 'KEY="VALUE"' pairs. Use JSON values.

**--priority-key** _int_

Priority key (1-5, lower numbers = higher priority). Tasks in a queue should be processed in close-to-priority-order. Default is 3 when not specified.

**--run-timeout** _duration_

Fail a Workflow Run if it lasts longer than `DURATION`.

**--search-attribute** _string[]_

Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times.

**--signal-input** _string[]_

Signal input value. Use JSON content or set --signal-input-meta to override. Can't be combined with --signal-input-file. Can be passed multiple times to pass multiple arguments.

**--signal-input-base64** _bool_

Assume signal inputs are base64-encoded and attempt to decode them.

**--signal-input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --signal-input-meta to override. Can't be combined with --signal-input. Can be passed multiple times to pass multiple arguments.

**--signal-input-meta** _string[]_

Input signal payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times.

**--signal-name** _string_

Signal name. Required.

**--start-delay** _duration_

Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately.

**--static-details** _string_

Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines.

:::note

Option is experimental.

:::

**--static-summary** _string_

Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line.

:::note

Option is experimental.

:::

**--task-queue**, **-t** _string_

Workflow Task queue. Required.

**--task-timeout** _duration_

Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s")

**--type** _string_

Workflow Type name. Required.

**--workflow-id**, **-w** _string_

Workflow ID. If not supplied, the Service generates a unique ID.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## stack

Perform a Query on a Workflow Execution using a `__stack_trace`-type Query.
Display a stack trace of the threads and routines currently in use by the
Workflow for troubleshooting:

```
temporal workflow stack \
    --workflow-id YourWorkflowId
```

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

**Flags:**

**--reject-condition** _string-enum_

Optional flag to reject Queries based on Workflow state. Accepted values: not_open, not_completed_cleanly.

**--run-id**, **-r** _string_

Run ID.

**--workflow-id**, **-w** _string_

Workflow ID. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## start

Start a new Workflow Execution. Returns the Workflow- and Run-IDs:

```
temporal workflow start \
    --workflow-id YourWorkflowId \
    --type YourWorkflow \
    --task-queue YourTaskQueue \
    --input '{"some-key": "some-value"}'
```

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

**Flags:**

**--cron** _string_

Cron schedule for the Workflow.

**--execution-timeout** _duration_

Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks.

**--fail-existing** _bool_

Fail if the Workflow already exists.

**--fairness-key** _string_

Fairness key (max 64 bytes) for proportional task dispatch. Tasks with same key share capacity based on their weight.

**--fairness-weight** _float_

Weight [0.001-1000] for this fairness key. Keys are dispatched proportionally to their weights.

**--id-conflict-policy** _string-enum_

Determines how to resolve a conflict when spawning a new Workflow Execution with a particular Workflow Id used by an existing Open Workflow Execution. Accepted values: Fail, UseExisting, TerminateExisting.

**--id-reuse-policy** _string-enum_

Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning.

**--input**, **-i** _string[]_

Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.

**--input-base64** _bool_

Assume inputs are base64-encoded and attempt to decode them.

**--input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.

**--input-meta** _string[]_

Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. Repeated metadata keys are applied to the corresponding inputs in the provided order.

**--memo** _string[]_

Memo using 'KEY="VALUE"' pairs. Use JSON values.

**--priority-key** _int_

Priority key (1-5, lower numbers = higher priority). Tasks in a queue should be processed in close-to-priority-order. Default is 3 when not specified.

**--run-timeout** _duration_

Fail a Workflow Run if it lasts longer than `DURATION`.

**--search-attribute** _string[]_

Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times.

**--start-delay** _duration_

Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately.

**--static-details** _string_

Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines.

:::note

Option is experimental.

:::

**--static-summary** _string_

Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line.

:::note

Option is experimental.

:::

**--task-queue**, **-t** _string_

Workflow Task queue. Required.

**--task-timeout** _duration_

Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s")

**--type** _string_

Workflow Type name. Required.

**--workflow-id**, **-w** _string_

Workflow ID. If not supplied, the Service generates a unique ID.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## start-update-with-start

Send a message to a Workflow Execution to invoke an Update handler, and wait for
the update to be accepted or rejected. If the Workflow Execution is not running,
then a new workflow execution is started and the update is sent.

Experimental.

```
temporal workflow start-update-with-start \
  --update-name YourUpdate \
  --update-input '{"update-key": "update-value"}' \
  --update-wait-for-stage accepted \
  --workflow-id YourWorkflowId \
  --type YourWorkflowType \
  --task-queue YourTaskQueue \
  --id-conflict-policy Fail \
  --input '{"wf-key": "wf-value"}'
```

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

**Flags:**

**--cron** _string_

Cron schedule for the Workflow.

**--execution-timeout** _duration_

Fail a WorkflowExecution if it lasts longer than `DURATION`. This time-out includes retries and ContinueAsNew tasks.

**--fail-existing** _bool_

Fail if the Workflow already exists.

**--fairness-key** _string_

Fairness key (max 64 bytes) for proportional task dispatch. Tasks with same key share capacity based on their weight.

**--fairness-weight** _float_

Weight [0.001-1000] for this fairness key. Keys are dispatched proportionally to their weights.

**--id-conflict-policy** _string-enum_

Determines how to resolve a conflict when spawning a new Workflow Execution with a particular Workflow Id used by an existing Open Workflow Execution. Accepted values: Fail, UseExisting, TerminateExisting.

**--id-reuse-policy** _string-enum_

Re-use policy for the Workflow ID in new Workflow Executions. Accepted values: AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning.

**--input**, **-i** _string[]_

Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.

**--input-base64** _bool_

Assume inputs are base64-encoded and attempt to decode them.

**--input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.

**--input-meta** _string[]_

Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. Repeated metadata keys are applied to the corresponding inputs in the provided order.

**--memo** _string[]_

Memo using 'KEY="VALUE"' pairs. Use JSON values.

**--priority-key** _int_

Priority key (1-5, lower numbers = higher priority). Tasks in a queue should be processed in close-to-priority-order. Default is 3 when not specified.

**--run-id**, **-r** _string_

Run ID. If unset, looks for an Update against the currently-running Workflow Execution.

**--run-timeout** _duration_

Fail a Workflow Run if it lasts longer than `DURATION`.

**--search-attribute** _string[]_

Search Attribute in `KEY=VALUE` format. Keys must be identifiers, and values must be JSON values. For example: `'YourKey={"your": "value"}'`. Can be passed multiple times.

**--start-delay** _duration_

Delay before starting the Workflow Execution. Can't be used with cron schedules. If the Workflow receives a signal or update prior to this time, the Workflow Execution starts immediately.

**--static-details** _string_

Static Workflow details for human consumption in UIs. Uses Temporal Markdown formatting, may be multiple lines.

:::note

Option is experimental.

:::

**--static-summary** _string_

Static Workflow summary for human consumption in UIs. Uses Temporal Markdown formatting, should be a single line.

:::note

Option is experimental.

:::

**--task-queue**, **-t** _string_

Workflow Task queue. Required.

**--task-timeout** _duration_

Fail a Workflow Task if it lasts longer than `DURATION`. This is the Start-to-close timeout for a Workflow Task. (default "10s")

**--type** _string_

Workflow Type name. Required.

**--update-first-execution-run-id** _string_

Parent Run ID. The update is sent to the last Workflow Execution in the chain started with this Run ID.

**--update-id** _string_

Update ID. If unset, defaults to a UUID.

**--update-input** _string[]_

Update input value. Use JSON content or set --update-input-meta to override. Can't be combined with --update-input-file. Can be passed multiple times to pass multiple arguments.

**--update-input-base64** _bool_

Assume update inputs are base64-encoded and attempt to decode them.

**--update-input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --update-input-meta to override. Can't be combined with --update-input. Can be passed multiple times to pass multiple arguments.

**--update-input-meta** _string[]_

Input update payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times.

**--update-name** _string_

Update name. Required.

**--update-wait-for-stage** _string-enum_

Update stage to wait for. The only option is `accepted`, but this option is required. This is to allow a future version of the CLI to choose a default value. Required. Accepted values: accepted.

**--workflow-id**, **-w** _string_

Workflow ID. If not supplied, the Service generates a unique ID.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## terminate

Terminate a Workflow Execution:

```
temporal workflow terminate \
    --reason YourReasonForTermination \
    --workflow-id YourWorkflowId
```

The reason is optional and defaults to the current user's name. The reason
is stored in the Event History as part of the `WorkflowExecutionTerminated`
event. This becomes the closing Event in the Workflow Execution's history.

Executions may be terminated in bulk via a visibility Query list filter:

```
temporal workflow terminate \
    --query YourQuery \
    --reason YourReasonForTermination
```

Workflow code cannot see or respond to terminations. To perform clean-up work
in your Workflow code, use `temporal workflow cancel` instead.

Visit https://docs.temporal.io/visibility to read more about Search Attributes
and Query creation. See `temporal batch --help` for a quick reference.

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

**Flags:**

**--query**, **-q** _string_

Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query.

**--reason** _string_

Reason for termination. Defaults to message with the current user's name.

**--rps** _float_

Limit batch's requests per second. Only allowed if query is present.

**--run-id**, **-r** _string_

Run ID. Can only be set with --workflow-id. Do not use with --query.

**--workflow-id**, **-w** _string_

Workflow ID. You must set either --workflow-id or --query.

**--yes**, **-y** _bool_

Don't prompt to confirm termination. Can only be used with --query.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## trace

Display the progress of a Workflow Execution and its child workflows with a
real-time trace. This view helps you understand how Workflows are proceeding:

```
temporal workflow trace \
    --workflow-id YourWorkflowId
```

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

**Flags:**

**--concurrency** _int_

Number of Workflow Histories to fetch at a time. (default "10")

**--depth** _int_

Set depth for your Child Workflow fetches. Pass -1 to fetch child workflows at any depth. (default "-1")

**--fold** _string[]_

Fold away Child Workflows with the specified statuses. Case-insensitive. Ignored if --no-fold supplied. Available values: running, completed, failed, canceled, terminated, timedout, continueasnew. Can be passed multiple times.

**--no-fold** _bool_

Disable folding. Fetch and display Child Workflows within the set depth.

**--run-id**, **-r** _string_

Run ID.

**--workflow-id**, **-w** _string_

Workflow ID. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## update

An Update is a synchronous call to a Workflow Execution that can change its
state, control its flow, and return a result.

### describe

Given a Workflow Execution and an Update ID, return information about its current status, including
a result if it has finished.

```
temporal workflow update describe \
    --workflow-id YourWorkflowId \
    --update-id YourUpdateId
```

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

**Flags:**

**--run-id**, **-r** _string_

Run ID. If unset, updates the currently-running Workflow Execution.

**--update-id** _string_

Update ID. Must be unique per Workflow Execution. Required.

**--workflow-id**, **-w** _string_

Workflow ID. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### execute

Send a message to a Workflow Execution to invoke an Update handler, and wait for
the update to complete or fail. You can also use this to wait for an existing
update to complete, by submitting an existing update ID.

```
temporal workflow update execute \
    --workflow-id YourWorkflowId \
    --name YourUpdate \
    --input '{"some-key": "some-value"}'
```

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

**Flags:**

**--first-execution-run-id** _string_

Parent Run ID. The update is sent to the last Workflow Execution in the chain started with this Run ID.

**--input**, **-i** _string[]_

Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.

**--input-base64** _bool_

Assume inputs are base64-encoded and attempt to decode them.

**--input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.

**--input-meta** _string[]_

Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. Repeated metadata keys are applied to the corresponding inputs in the provided order.

**--name** _string_

Handler method name. Required.

**--run-id**, **-r** _string_

Run ID. If unset, looks for an Update against the currently-running Workflow Execution.

**--update-id** _string_

Update ID. If unset, defaults to a UUID.

**--workflow-id**, **-w** _string_

Workflow ID. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### result

Given a Workflow Execution and an Update ID, wait for the Update to complete or fail and
print the result.

```
temporal workflow update result \
    --workflow-id YourWorkflowId \
    --update-id YourUpdateId
```

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

**Flags:**

**--run-id**, **-r** _string_

Run ID. If unset, updates the currently-running Workflow Execution.

**--update-id** _string_

Update ID. Must be unique per Workflow Execution. Required.

**--workflow-id**, **-w** _string_

Workflow ID. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

### start

Send a message to a Workflow Execution to invoke an Update handler, and wait for
the update to be accepted or rejected. You can subsequently wait for the update
to complete by using `temporal workflow update execute`.

```
temporal workflow update start \
    --workflow-id YourWorkflowId \
    --name YourUpdate \
    --input '{"some-key": "some-value"}'
    --wait-for-stage accepted
```

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

**Flags:**

**--first-execution-run-id** _string_

Parent Run ID. The update is sent to the last Workflow Execution in the chain started with this Run ID.

**--input**, **-i** _string[]_

Input value. Use JSON content or set --input-meta to override. Can't be combined with --input-file. Can be passed multiple times to pass multiple arguments.

**--input-base64** _bool_

Assume inputs are base64-encoded and attempt to decode them.

**--input-file** _string[]_

A path or paths for input file(s). Use JSON content or set --input-meta to override. Can't be combined with --input. Can be passed multiple times to pass multiple arguments.

**--input-meta** _string[]_

Input payload metadata as a `KEY=VALUE` pair. When the KEY is "encoding", this overrides the default ("json/plain"). Can be passed multiple times. Repeated metadata keys are applied to the corresponding inputs in the provided order.

**--name** _string_

Handler method name. Required.

**--run-id**, **-r** _string_

Run ID. If unset, looks for an Update against the currently-running Workflow Execution.

**--update-id** _string_

Update ID. If unset, defaults to a UUID.

**--wait-for-stage** _string-enum_

Update stage to wait for. The only option is `accepted`, but this option is  required. This is to allow a future version of the CLI to choose a default value. Required. Accepted values: accepted.

**--workflow-id**, **-w** _string_

Workflow ID. Required.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

## update-options

```
+---------------------------------------------------------------------+
| CAUTION: Worflow update-options is experimental. Workflow Execution |
| properties are subject to change.                                   |
+---------------------------------------------------------------------+
```

Modify properties of Workflow Executions:

```
temporal workflow update-options [options]
```

It can override the Worker Deployment configuration of a
Workflow Execution, which controls Worker Versioning.

For example, to force Workers in the current Deployment execute the
next Workflow Task change behavior to `auto_upgrade`:

```
temporal workflow update-options \
    --workflow-id YourWorkflowId \
    --versioning-override-behavior auto_upgrade
```

or to pin the workflow execution to a Worker Deployment, set behavior
to `pinned`:

```
temporal workflow update-options \
    --workflow-id YourWorkflowId \
    --versioning-override-behavior pinned \
    --versioning-override-deployment-name YourDeploymentName \
    --versioning-override-build-id YourDeploymentBuildId
```

To remove any previous overrides, set the behavior to
`unspecified`:

```
temporal workflow update-options \
    --workflow-id YourWorkflowId \
    --versioning-override-behavior unspecified
```

To see the current override use `temporal workflow describe`

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

**Flags:**

**--query**, **-q** _string_

Content for an SQL-like `QUERY` List Filter. You must set either --workflow-id or --query.

**--reason** _string_

Reason for batch operation. Only use with --query. Defaults to user name.

**--rps** _float_

Limit batch's requests per second. Only allowed if query is present.

**--run-id**, **-r** _string_

Run ID. Only use with --workflow-id. Cannot use with --query.

**--versioning-override-behavior** _string-enum_

Override the versioning behavior of a Workflow. Required. Accepted values: unspecified, pinned, auto_upgrade.

**--versioning-override-build-id** _string_

When overriding to a `pinned` behavior, specifies the Build ID of the version to target.

**--versioning-override-deployment-name** _string_

When overriding to a `pinned` behavior, specifies the Deployment Name of the version to target.

**--workflow-id**, **-w** _string_

Workflow ID. You must set either --workflow-id or --query.

**--yes**, **-y** _bool_

Don't prompt to confirm signaling. Only allowed when --query is present.

**Global Flags:**

**--address** _string_

Temporal Service gRPC endpoint. (default "localhost:7233")

**--api-key** _string_

API key for request.

**--client-authority** _string_

Temporal gRPC client :authority pseudoheader.

**--client-connect-timeout** _duration_

The client connection timeout. 0s means no timeout.

**--codec-auth** _string_

Authorization header for Codec Server requests.

**--codec-endpoint** _string_

Remote Codec Server endpoint.

**--codec-header** _string[]_

HTTP headers for requests to codec server. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers.

**--color** _string-enum_

Output coloring. Accepted values: always, never, auto. (default "auto")

**--command-timeout** _duration_

The command execution timeout. 0s means no timeout.

**--config-file** _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.

:::note

Option is experimental.

:::

**--disable-config-env** _bool_

If set, disables loading environment config from environment variables.

:::note

Option is experimental.

:::

**--disable-config-file** _bool_

If set, disables loading environment config from config file.

:::note

Option is experimental.

:::

**--env** _string_

Active environment name (`ENV`). (default "default")

**--env-file** _string_

Path to environment settings file. Defaults to `$HOME/.config/temporalio/temporal.yaml`.

**--grpc-meta** _string[]_

HTTP headers for requests. Format as a `KEY=VALUE` pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as `TEMPORAL_GRPC_META_[name]`.

**--identity** _string_

The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".

**--log-format** _string-enum_

Log format. Accepted values: text, json. (default "text")

**--log-level** _string-enum_

Log level. Default is "info" for most commands and "warn" for `server start-dev`. Accepted values: debug, info, warn, error, never. (default "info")

**--namespace**, **-n** _string_

Temporal Service Namespace. (default "default")

**--no-json-shorthand-payloads** _bool_

Raw payload output, even if the JSON option was used.

**--output**, **-o** _string-enum_

Non-logging data output format. Accepted values: text, json, jsonl, none. (default "text")

**--profile** _string_

Profile to use for config file.

:::note

Option is experimental.

:::

**--time-format** _string-enum_

Time format. Accepted values: relative, iso, raw. (default "relative")

**--tls** _bool_

Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.

**--tls-ca-data** _string_

Data for server CA certificate. Can't be used with --tls-ca-path.

**--tls-ca-path** _string_

Path to server CA certificate. Can't be used with --tls-ca-data.

**--tls-cert-data** _string_

Data for x509 certificate. Can't be used with --tls-cert-path.

**--tls-cert-path** _string_

Path to x509 certificate. Can't be used with --tls-cert-data.

**--tls-disable-host-verification** _bool_

Disable TLS host-name verification.

**--tls-key-data** _string_

Private certificate key data. Can't be used with --tls-key-path.

**--tls-key-path** _string_

Path to x509 private key. Can't be used with --tls-key-data.

**--tls-server-name** _string_

Override target TLS server name.

---

## Audit Logs - AWS Kinesis

## Configure Audit Logs using AWS Kinesis {#configure-audit-log}

To set up Audit Logs, you must have an Amazon Web Services (AWS) account and set up Kinesis Data Streams.

1. If you don't have an AWS account, follow the instructions from AWS in [Create and activate an AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
2. To set up Kinesis Data Streams, open the [AWS Management Console](https://aws.amazon.com/console/), search for Kinesis, and start the setup process.

You can use [this AWS CloudFormation template](https://temporal-auditlogs-config.s3.us-west-2.amazonaws.com/cloudformation/iam-role-for-temporal-audit-logs.yaml) to create an IAM role with access to a Kinesis stream you have in your account.

Be aware that Kinesis has a rate limit of 1,000 messages per second and quotas for both the number of records written and the size of the records.
For more information, see [Why is my Kinesis data stream throttling?](https://aws.amazon.com/premiumsupport/knowledge-center/kinesis-data-stream-throttling/)

### Create an Audit Log sink

1. In the Temporal Cloud UI, select **Settings**.
1. On the **Settings** page, select **Audit Logs**.
1. In the **Audit Log Integration** card, select **Setup**.
1. On the **Audit Log Integration** page, choose your **Access method** (either **Auto** or **Manual**).
   - **Auto:** Configure the AWS CloudFormation stack in your AWS account from the Cloud UI.
   - **Manual:** Use a generated AWS CloudFormation template to set up Kinesis manually.
1. In **Kinesis ARN**, paste the Kinesis ARN from your AWS account.
1. In **Role name**, provide a name for a new IAM Role.
1. In **Select an AWS region**, select the appropriate region for your Kinesis stream.

If you chose the **Auto** access method, continue with the following steps:

1. Select **Save and launch stack**.
1. In **Stack name** in the AWS CloudFormation console, specify a name for the stack.
1. In the lower-right corner of the page, select **Create stack**.

If you chose the **Manual** access method, continue with the following steps:

1. Select **Save and download template**.
1. Open the [AWS CloudFormation console](https://console.aws.amazon.com/cloudformation/).
1. Select **Create Stack**.
1. On the **Create stack** page, select **Template is ready** and **Update a template file**.
1. Select **Choose file** and specify the template you generated in step 1.
1. Select **Next** on this page and on the next two pages.
1. On the **Review** page, select **Create stack**.

To ensure that Audit Logs can flow into the Kinesis stream, you can use the **Verify** button to confirm it is set up correctly. This validates that Temporal can successfully write to your stream.
If everything is configured correctly, you will see a `Success` status indicating Temporal has written to the kinesis stream.

## Consume an Audit Log {#consume-an-audit-log}

**How to consume an Audit Log**

After you create an Audit Log sink, wait for the logs to flow into the Kinesis stream.
You will see the first logs within 10 minutes after you configure the sink.

:::note

You must configure and implement your own consumer of the Kinesis stream.
For an example, see [Example of consuming an Audit Log](#example-of-consuming-an-audit-log).

:::

### Example of consuming an Audit Log

The following Go code is an example of consuming Audit Logs from a Kinesis stream and delivering them to an S3 bucket.

```go
func main() {
   fmt.Println("print audit log from S3")
   cfg, err := config.LoadDefaultConfig(context.TODO(),
      config.WithSharedConfigProfile("your_profile"),
   )
   if err != nil {
      fmt.Println(err)
   }
   s3Client := s3.NewFromConfig(cfg)
   response, err := s3Client.GetObject(
      context.Background(),
      &s3.GetObjectInput{
         Bucket: aws.String("your_bucket_name"),
         Key:    aws.String("your_s3_file_path")})
   if err != nil {
      fmt.Println(err)
   }
   defer response.Body.Close()

   content, err := io.ReadAll(response.Body)

   fmt.Println(string(content))
}
```

The preceding code also prints the logs in the terminal.
The following is a sample result.

```json
{
  "emit_time": "2023-11-14T07:56:55Z",
  "level": "LOG_LEVEL_INFO",
  "caller_ip_address": "10.1.2.3, 10.4.5.6",
  "user_email": "user1@example.com",
  "operation": "DeleteUser",
  "details": {
    "target_users": ["d7dca96f-adcc-417d-aafc-e8f5d2ba9fe1"],
    "search_attribute_update": {}
  },
  "status": "OK",
  "category": "LOG_CATEGORY_ADMIN",
  "log_id": "0mc69c0323b871293ce231dd1c7fb639",
  "request_id": "445297d3-43a7-4793-8a04-1b1dd1999640",
  "principal": {
    "id": "988cb80b-d6be-4bb5-9c87-d09f93f58ed3",
    "type": "user",
    "name": "user1@example.com"
  }
}
```

---

## Audit Logs - GCP Pub/Sub

## Manual Setup Prerequisites

:::note

These steps are only required for manual setup.
If you use Terraform for your deployment, you don't need to complete these prerequisites.

:::

Before configuring the manual Audit Log sink, complete the following steps in Google Cloud:

1. Create a Pub/Sub topic and make a note of its topic name, such as `test-auditlog`.
1. Set up a service account in the same project in Google Cloud and follow the instructions in the
   Temporal Cloud UI to configure the permissions for that service account.

## Create an Audit Log sink

1. In the Temporal Cloud UI, select **Settings**.
1. On the **Settings** page, select **Audit Logs**.
1. In the **Audit Logs Integration** card, select **Setup**.
1. On the **Audit Log Integration** page, select **Pub/Sub**.
1. In the **service account email** field, enter the email of the service account you created in the prerequisites.
1. In the **Topic name** field, enter the topic name of the Pub/Sub topic you created in the prerequisites.
1. There are two ways to configure the service account to write to the Pub/Sub sink: select **Manual** to configure the account manually, or **Deploy with Terraform** to use Terraform.
   If you use Terraform, you don't need to complete the prerequisite steps above.
1. Follow the instructions in the Temporal Cloud UI for the method you chose.
1. To ensure that audit logs can reach your Pub/Sub topic, you can use the **Verify** button to confirm it is set up correctly. This validates that Temporal can successfully write to your topic.
If everything is configured correctly, you will see a `Success` status indicating Temporal has written to the Pub/Sub topic.
1. Click **Create** to configure the audit log.
   Audit Logs will begin to show up in Pub/Sub within 10 minutes 

![Temporal Cloud UI Setup for Audit Logs with GCP Pub/Sub](/img/cloud/gcp/audit-logging-pub-sub-gcp.png)

:::info MORE INFORMATION

For more details, refer to [Audit Logs with Temporal Cloud](https://docs.temporal.io/cloud/audit-logs).

:::

---

## Audit Logs

Audit Logs is a feature of [Temporal Cloud](/cloud/overview) that provides forensic access information for a variety of operations in the Temporal Cloud control plane.

Audit Logs answers "who, when, and what" questions about Temporal Cloud resources.
These answers can help you evaluate the security of your organization, and they can provide information that you need to satisfy audit and compliance requirements.

You need the Account Owner or Global Administrator role to view Audit Logs via UI, use the API, or to configure an Audit Log Integration with [AWS Kinesis](/cloud/audit-logs-aws) or [GCP Pub/Sub](/cloud/audit-logs-gcp).

:::info

Audit Logs do NOT capture data plane events, like Workflow Start, Workflow Terminate, Schedule Create, etc.
Instead, explore the [Export](/cloud/export) feature, which does let you send closed Workflow Histories to external storage.

:::

## Which events are supported by Audit Logs? {#supported-events}

- Account
  - `ChangeAccountPlanType`: Change Account Plan Type
  - `UpdateAccountAPI`: Configure Audit Logs, Configure Observability Endpoint
- API Keys
  - `CreateAPIKey`: Create API Key
  - `DeleteAPIKey`: Delete API Key
  - `UpdateAPIKey`: Update API Key
- Connectivity Rules
  - `CreateConnectivityRule`: Create Connectivity Rule
  - `DeleteConnectivityRule`: Delete Connectivity Rule
- Namespace
  - `CreateNamespaceAPI`: Create Namespace
  - `DeleteNamespaceAPI`: Delete Namespace
  - `FailoverNamespacesAPI`: Failover (for High Availability Namespaces)
  - `RenameCustomSearchAttributeAPI`: Rename Custom Search Attribute
  - `UpdateNamespaceAPI`: Includes retention period changes, replica edits, authentication method updates, custom search attribute updates, and connectivity rule bindings
- Namespace Export
  - `CreateNamespaceExportSink`: Create Namespace Export Sink
  - `DeleteNamespaceExportSink`: Delete Namespace Export Sink
  - `UpdateNamespaceExportSink`: Update Namespace Export Sink
  - `ValidateNamespaceExportSink`: Validate Namespace Export Sink
- Nexus Endpoint
  - `CreateNexusEndpoint`: Create Nexus Endpoint
  - `DeleteNexusEndpoint`: Delete Nexus Endpoint
  - `UpdateNexusEndpoint`: Update Nexus Endpoint
- Service Accounts
  - `CreateServiceAccount`: Create Service Account
  - `CreateServiceAccountAPIKey`: Create Service Account API Key
  - `DeleteServiceAccount`: Delete Service Account
  - `UpdateServiceAccount`: Update Service Account
- User
  - `CreateUserAPI`: Create Users
  - `DeleteUserAPI`: Delete Users
  - `InviteUsersAPI`: Invite Users
  - `SetUserNamespaceAccessAPI`: Set User Namespace Access
  - `UpdateIdentityNamespacePermissionsAPI`: Update Identity Namespace Permissions
  - `UpdateUserAPI`: Update User Account-level Roles
  - `UpdateUserNamespacePermissionsAPI`: Update User Namespace Permissions
- User Groups
  - `CreateUserGroup`: Create User Group
  - `DeleteUserGroup`: Delete User Group
  - `SetUserGroupNamespaceAccess`: Set User Group Namespace Access
  - `UpdateUserGroup`: Update User Group

### Audit Log format

:::info DEPRECATION NOTICE

The following fields are deprecated and are planned for removal on or after April 1 2026. 

- `user_email`.  This field is duplicated by `principal.name` for principals of type `user`. Other principal types do not have associated emails.
- `level`.  This field is duplicated by `status`.
- `caller_ip_address`.  This field is replaced by `x_forwarded_for`.
- `details`.  This field is replaced by `raw_details` that includes request details.
- `category`.  This field is no longer used.

:::

Audit Logs use the following JSON format:

```json
{
  "operation":  // Operation that was performed
  "principal": // Information about who initiated the operation
  "details":  // DEPRECATED, see raw_details
  "raw_details": // details about the request
  "user_email":  // DEPRECATED, use principal.user where applicable
  "x_forwarded_for": // the IP address making the call
  "caller_ip_address": // DEPRECATED, use x_forwarded_for
  "category":  // DEPRECATED, no longer used
  "emit_time": // Time the operation was recorded
  "level": // DEPRECATED, use status
  "log_id": // Unique ID of the log entry
  "request_id": // Optional async request id set by the user when sending a request
  "status": // Status, such as OK or ERROR
  "version": // Version of the log entry
}
```

:::note

The [`X-Forwarded-For`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) format is a comma-separated list of IP addresses which should be evaluated from the last to the first, until meeting the first untrusted IP address of the list. This allows for instance to consider proxies in the path.

Temporal provides the caller IP address in that format to allow customers to identify a caller IP address even if one (or more proxies) are in the network path to reach Temporal Cloud.

:::

### Example of an Audit Log

```json
[
  {
    "operation": "UserLogin",
    "status": "OK",
    "version": 2,
    "logId": "edb3aa3e-78c4-48fc-9c7e-2078c6989775",
    "xForwardedFor": "10.1.2.3",
    "asyncOperationId": "",
    "emitTime": {
      "$typeName": "google.protobuf.Timestamp",
      "seconds": 1759436617,
      "nanos": 48000000
    },
    "principal": {
      "type": "user",
      "id": "",
      "name": "user@email.com",
      "apiKeyId": ""
    }
  },
  {
    "operation": "UserLogin",
    "status": "OK",
    "version": 2,
    "logId": "5fe6a81e-8d3c-4f4d-88a5-52db864c9ea5",
    "xForwardedFor": "10.1.2.3",
    "asyncOperationId": "",
    "emitTime": {
      "seconds": 1759178573,
      "nanos": 671000000
    },
    "principal": {
      "type": "user",
      "id": "",
      "name": "user@email.com",
      "apiKeyId": ""
    }
  }
]
```

## How to configure an Audit Log Integration {#configure-audit-logs}

Audit Logs can be configured in AWS Kinesis or GCP Pub/Sub.

- [AWS Kinesis Instructions](/cloud/audit-logs-aws)
- [GCP Pub/Sub Instructions](/cloud/audit-logs-gcp)

## How to troubleshoot Audit Log sink {#troubleshoot-audit-logs}

The Audit Logs page of the Temporal Cloud UI provides the current status of an Audit Log Integration.

- If an error is detected, a summary of the error appears below the page title.
- If the Audit Log Integration is functioning normally, an **On** badge appears next to the page heading.

After an Admin Operation is performed, users can see Audit Log messages flow through the stream.

Upon successful configuration of the Audit Log sink and set up of a stream, you will receive events within the hour of setup.
Temporal is able to retain Audit Log information for up to 30 days.
To retrieve logs up to the past 30 days, you will need to file a request.

If you experience an issue with an Audit Log sink, we can provide the missing audit information.
Open a support ticket to request assistance.

## How to delete an Audit Log sink {#delete-an-audit-log-sink}

To delete an Audit Log sink, follow these steps:

1. In the Temporal Cloud UI, select **Settings**.
1. On the **Settings** page, select **Audit Logs**.
1. In the **Audit Logs Integration** card, select **Edit**.
1. At the bottom of the **Audit Logs Integration** page, choose **Delete**.

After you confirm the deletion, the Audit Log Sink is removed from your account and logs stop flowing to your stream.

## View an Audit Log {#view-an-audit-log}

An Audit Log can be viewed in the Temporal Cloud UI.
1. In the Temporal Cloud UI, select **Settings**.
1. On the **Settings** page, select **Audit Logs**.

Up to 1000 events can be downloaded from the Audit Log UI to a local file.

## Access an Audit Log via API {#audit-log-api}

An Audit Log can be accessed using the [Temporal Cloud Ops API](/ops). Use the API to access
an Audit Log if you wish to make dashboards for viewing an Audit Log outside of Temporal Cloud.
If your goal is to export an Audit Log, it is better to use an Audit Log sink and capture each 
entry as it is generated.

Audit Logs are accessible for the past 30 days using the API.

The API allows:
- StartTimeInclusive: Filter for UTC time >= (defaults to 30 days ago) - optional
- EndTimeExclusive: Filter for UTC time < (defaults to current time) - optional
- PageSize: Cannot exceed 1000. Defaults to 100. - optional
- PageToken: The page token if this is continuing from another response - optional

---

## Exporting Workflow Event History to AWS S3

## Prerequisites

Before configuring the Export Sink, ensure you have the following:

- An AWS S3 bucket.
   - The S3 bucket must reside in the same region as your Namespace.
- (Optional) An IAM role that has write permission to the above S3 bucket.
   - You can follow the automation in the UI to create the IAM role. Please pre-create the role if setting up Export via terraform/tcld.
- (Optional) A KMS ARN associated with the S3 bucket.

## Configure Workflow History export

There are multiple ways to configure export: through the [Temporal Cloud UI](#using-temporal-cloud-ui), [`tcld`](#using-tcld), or [`terraform`](#using-terraform).

### Using Temporal Cloud UI

You can use the Temporal Cloud UI to configure the Workflow History Export.

The Temporal Cloud UI provides two ways for configuring Workflow History Export:

- [Automated setup](#automated-setup) (recommended): The Cloud UI launches the AWS CloudFormation Console to create a stack with write permission to the S3 bucket.
- [Manual setup](#manual-setup): The Cloud UI provides a CloudFormation template for users to manually configure a CloudFormation stack.

:::info Why does Temporal Cloud provision multiple internal IAM roles to trust for Export?

Temporal Cloud creates multiple intermediary IAM roles for export operations for security purposes. 
The system randomly selects from these roles when writing to your storage sink, which provides several benefits:

- **Security isolation**: If one IAM role is compromised or needs to be decommissioned, other IAM roles remain available
- **Load distribution**: Avoids relying on a single IAM role, reducing security risk
- **Warm standby**: Keeps multiple IAM roles active to avoid potential throttling when switching between IAM roles
- **Reliability**: Provides resilience against cloud provider account-level issues that could affect a single IAM role

This approach prioritizes security and availability, ensuring robust export operations even if individual IAM roles encounter issues.
:::

The following steps guide you through setting up Workflow History Export using the Temporal Cloud UI.

![](/img/cloud/gcp/export-sink-ui.png)

:::tip

Don't forget to click **Create** at the end of your setup to confirm your export.

:::

#### Automated setup

You can use the automated setup to create a CloudFormation stack with write permission to your S3 bucket.
Make sure to verify the export setup before you save the configuration.

1. Open the Temporal Cloud UI and navigate to the Namespace you want to configure.
2. Select **Configure** from the **Export** card.
3. Provide the following information to configure the export sink and then select **Create and launch stack**:
   - Name: A name for the export sink.
   - AWS S3 Bucket Name: The name of the configured AWS S3 bucket to send Closed Workflow Histories to.
   - AWS Account ID: The AWS account ID.
   - Role Name: The name of the AWS IAM role to use for the CloudFormation stack that has write permission to the S3 bucket.
   - KMS ARN: (optional) The ARN of the AWS KMS key to use for encryption of the exported Workflow History.
4. You will be taken to the CloudFormation Console to create the stack with pre-populated information.
   - Review the information and then select **Create stack**.

#### Manual setup

You can manually configure a CloudFormation stack using the provided template.

1. Open the Temporal Cloud UI and navigate to the Namespace you want to configure.
2. Select **Configure** from the **Export** card.
3. Select **Manual** from **Access method**.
   - Enter the Template URL into your web browser to download your copy of the CloudFormation template.
   - Configure the CloudFormation template for your export sink.
   - Follow the steps in the [AWS documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-using-console-create-stack-template.html) by uploading the template to the CloudFormation console.

### Using `tcld`

Run the `tcld namespace export s3 create` command and provide the following information:

- `--namespace`: The Namespace to configure export for.
- `--sink-name`: The name of the export sink.
- `--role-arn`: The ARN of the AWS IAM role to use for the CloudFormation stack that has write permission to the S3 bucket.
- `--s3-bucket-name`: The name of the AWS S3 bucket.

For example:

```command
tcld namespace export s3 create --namespace "your-namespace.your-account" --sink-name "your-sink-name" --role-arn "arn:aws:iam::123456789012:role/test-sink" --s3-bucket-name "your-aws-s3-bucket-name"
```

Retrieve the status of this command by running the `tcld namespace export s3 get` command.

For example:

```command
tcld namespace export s3 get --namespace "your-namespace.your-account" --sink-name "your-sink-name"
```

The following is an example of the output:

```json
{
  "name": "your-sink-name",
  "resourceVersion": "a6442895-1c07-4da4-aaca-58d57d338345",
  "state": "Active",
  "spec": {
    "name": "your-sink-name",
    "enabled": true,
    "destinationType": "S3",
    "s3Sink": {
      "roleName": "your-export-test",
      "bucketName": "your-export-test",
      "region": "us-east-1",
      "kmsArn": "",
      "awsAccountId": "123456789012"
    }
  },
  "health": "Ok",
  "errorMessage": "",
  "latestDataExportTime": "0001-01-01T00:00:00Z",
  "lastHealthCheckTime": "2023-08-14T21:30:02Z"
}
```

### Using `terraform`

See the [terraform export support](https://registry.terraform.io/providers/temporalio/temporalcloud/latest/docs/resources/namespace_export_sink) for setup instructions.

### Next Steps

- [Verify export setup](/cloud/export#verify)
- [Monitor export progress](/cloud/export#monitor)
- [Work with exported files](/cloud/export#working-with-exported-files)

---

## Capacity Modes

Each Namespace in Temporal has a rate limit, which is measure in [Actions](/cloud/pricing#action) per second. 
Temporal offers two different modes for adjusting capacity: On-Demand Capacity or Provisioned Capacity.
With On-Demand Capacity, Namespace capacity is increased automatically along with usage.
With Provisioned Capacity, you can control your capacity limits by requesting Temporal Resource Units (TRUs).

## Namespace Capacity

Namespaces in Temporal can be set to either an **On-Demand** or **Provisioned Capacity** Mode. 
These modes govern how limits are assigned to a Namespace.  

Actions Per Second (APS) is the primary limit for Namespaces and is based on the operating billable Actions that occur each second.
Some Actions can result in multiple back-end operations, so limits are also set on Requests Per Second (RPS) and Operations Per Second (OPS) to maintain reliability.

See [Service-level RPS limits](/references/dynamic-configuration#service-level-rps-limits) for more about RPS.
See the [operations list](/references/operation-list) for the list of operations.
See the [Actions page](/cloud/actions) for the list of actions.

:::tip Measuring throughput with APS, RPS, and OPS

APS, RPS, and OPS are all measures of throughput that apply to different aspects of Temporal.

APS, or Actions Per Second, is specific to Temporal Cloud. 
It measures the rate at which Actions, like starting or signaling a Workflow, can be performed in a specific Namespace. 
Temporal Cloud uses APS to protect the system from sudden major spikes in load. 

RPS, or Requests Per Second, is used in the Temporal Service, both in self-hosted Temporal and Temporal Cloud. 
It measures and controls the rate of gRPC requests to the Service. 
This is a lower-level measure that manages rates at the service level. 

OPS, or Operations per Second, is used by Temporal Cloud. 
An operation is anything a user does directly, or that Temporal does on behalf of the user in the background, that results in load on Temporal Server. 
This is a lower-level measure that manages rates across Temporal cloud services.

In summary, APS is a higher-level measure to limit and mitigate Action spikes in Temporal Cloud. 
RPS and OPS  are lower-level measures to control and balance request rates at the service level.

:::

### What happens when my Actions Rate exceeds my Limit?

When your Action rate exceeds your quota, Temporal Cloud throttles Actions until the rate matches your quota. 
Throttling means limiting the rate at which Actions are performed to prevent the Namespace from exceeding its APS limit. 
Your work is never lost and will continue at the limited pace until APS returns below the limit. 
Your rate limits can be adjusted automatically over time or provisioned manually with Capacity Modes.

We recommend tracking your Actions Rate and Limits using Temporal metrics to assess your use cases specific needs. 
See [Monitoring Trends Against Limits](/cloud/service-health#rps-aps-rate-limits) to track usage trends.

:::note Actions that don't count against APS
Actions that are external to the core Temporal service do not contribute to your APS. These Calls include:
* [Export](/cloud/export)
* Capacity Related Actions
:::

## On-Demand Capacity {#on-demand-capacity}

Using On-Demand Capacity, your rate limit grows automatically along with your usage. 

|               | Actions Per Second | Requests Per Second | Operations Per Second|
|---------------|--------------------|---------------------|----------------------|
| Default Limit | 500                | 2000                | 4000                 |

Scaling automatically adjusts based on the lesser of 4 * APS Average or 2 * APS P90 over the past 7 days.

If you experience usage spikes, you may hit a throughput limit. 
In that case, consider switching to [Provisioned Capacity](#provisioned-capacity). 
You can also optimize your workload to remain under the On-Demand limits. See [Best Practices for Managing APS Limits](/best-practices/managing-aps-limits) for more information. 

### What kind of throughput can I get on Temporal Cloud with On-Demand Capacity?

Each Namespace has a rate limit, which is measured in Actions per second (APS). 
A Namespace's default limit is set at 500 APS and automatically adjusts based on a formula that compares your average usage over the last 7 days and your usage at the 90th percentile, or P90. 
Your throughput limit will never fall below the default value. 
Under On-Demand capacity you are only charged for the Actions you use.

For example: If your average APS in the last 7 days was 200 APS, and your P90 was 500 APS, then your limit would be calculated as follows:
Greater of:
* Default limit of 500 APS
* The lesser of:
  * 4 * 200 APS Mean = 800 APS
  * 2 * 500 APS P90 = 1000 APS

This means that your default limit would be 800 APS.

![Usage graph showing increasing APS usage for one month, with occasional spikes, and a rising APS limit](/img/cloud/provisioned-capacity/usage_graph.png)

## Provisioned Capacity {#provisioned-capacity}

:::tip Support, stability, and dependency info

Provisioned Capacity is currently in [pre-release](/evaluate/development-production-features/release-stages#pre-release). 
Please contact your AE or Support to enable this feature.

:::

Provisioned Capacity provides an alternative to On-Demand Capacity by allowing you to control the limits on your Namespace based on your specific need.

|               | Actions Per Second | Requests Per Second | Operations Per Second|
|---------------|--------------------|---------------------|----------------------|
| TRU           | 500                | 2000                | 4000                 |

Customers can set 2, 3, 4, 6, 8, 10, 12 TRUs, subject to availability. TRUs can be adjusted hourly.

See [Capacity Mode Pricing](/cloud/pricing#capacity-modes-pricing) for pricing implications.

### What kind of throughput can I get with Temporal Cloud with Provisioned Capacity?

With Provisioned Capacity, you can set your rate limits by selecting the number of Temporal Resource Units (TRUs) on your Namespace.
Each TRU supports up to 500 APS and can be provisioned in groups of 2, 3, 4, 6, 8, 10, or 12 TRUs if there is capacity available in a region. 
When TRUs are requested we aim to provision the additional capacity within two minutes. 

:::tip Large TRU requests

For Requests in excess of 4 TRUs in regions outside of the US, we recommend submitting a support ticket to ensure capacity availability.

:::

### Provisioned Capacity Availability
The amount of capacity available within a region may vary. 
Temporal will check available capacity at the time of your request and aims to provision requested capacity within two minutes. 
If you need capacity beyond what is self-serviceable or available in a region, please [file a support ticket](https://docs.temporal.io/cloud/support#ticketing) indicating the limit, region, and timeframe that the capacity is needed. 

### When should I use Provisioned Capacity?

Provisioned Capacity works well when you’re aware of specific increases in load on your Namespace. For example:

* Planned events
* Unplanned events/usage spikes
* Known but sudden system spikes
* Load testing
* Migrating workloads

Depending on your usage patterns and your system monitoring, you can use Provisioned Capacity to quickly remedy rate limiting without contacting support.
You can also automate changes in capacity if you have a known event or a recurring usage pattern that produces predictable usage spikes. 

## Setting Capacity Modes
Capacity Modes and TRUs can be set via the Temporal Cloud UI, CLI, or API. 
Capacity modes can be set and adjusted by Global Admin and Namespace Admin. 

### Setting Capacity Modes from the UI

You can set Capacity Modes for an individual Namespace by navigating to the Namespace page in the Temporal Cloud UI (`https://cloud.temporal.io/namespaces/<Namespace ID>`). 
To view your current capacity configuration and change your capacity mode, navigate to the capacity tile and click *Manage Capacity*.

![Manage Capacity button in the Temporal UI](/img/cloud/provisioned-capacity/manage_capacity_button.png)

Under *Manage Capacity* you will be able to select between *On-Demand* and *Provisioned Capacity* modes. 
The *On-Demand* section will display your available On-Demand capacity. 
The *Provisioned* section will display the limit available with selected TRUs and the Included Actions required per hour. [See details on Provisioned Capacity Pricing](/cloud/pricing#capacity-modes-pricing). 

To switch to Provisioned capacity: 

1. Select the *Provisioned* radio button.
1. Specify the requested number of TRUs using the slider.
1. Check the dialog acknowledging potential pricing implications.
1. Click *Confirm*. 

In addition to the Capacity Mode selections, a summary of APS usage over the last seven days is included to help you estimate your current usage. 
For more detailed information, we recommend setting up metrics that track your APS and Limits. 
See [Monitoring Trends Against Limits](/cloud/service-health#rps-aps-rate-limits) to track usage trends.

![Manage Capacity panel in the Temporal UI](/img/cloud/provisioned-capacity/manage_capacity_panel.png)

### Setting Capacity Modes from the CLI

```command
tcld capacity update --namespace <namespace_name> --capacity-mode <on_demand|provisioned> --capacity-value <tru value> [--request–id <request_id> --resource-version <resource-version>]
```

Use this command to specify the Namespace name and configure the capacity settings:

* `--capacity-mode` sets the billing mode for the Namespace. Use `on_demand` for automatic scaling or `provisioned` for a fixed capacity allocation.
* `--capacity-value` sets the throughput value in TRUs (Temporal Resource Units).

Optional flags:

* `--request-id` specifies a request identifier for the asynchronous operation. If not specified, the server assigns one automatically.
* `--resource-version` specifies the resource version (etag) to update from. If not set, the CLI uses the latest version.

If using API key authentication with the `--api-key` flag, you must add it directly after the tcld command and before capacity update.

### Setting Capacity Modes from the API

Call the `UpdateNamespace` API after Namespace creation and define the desired capacity state as part of the capacity spec.

---

## AWS PrivateLink Connectivity

[AWS PrivateLink](https://aws.amazon.com/privatelink/) allows you to open a path to Temporal without opening a public egress.
It establishes a private connection between your Amazon Virtual Private Cloud (VPC) and Temporal Cloud.
This one-way connection means Temporal cannot establish a connection back to your service.
This is useful if normally you block traffic egress as part of your security protocols.
If you use a private environment that does not allow external connectivity, you will remain isolated.

## Requirements

Your AWS PrivateLink endpoint must be in the same region as your Temporal Cloud namespace. If using [replication for High Availability](/cloud/high-availability), the PL connection must be in the same region as one of the replicas.

AWS Cross Region endpoints are not supported.

## Creating an AWS PrivateLink connection

Set up PrivateLink connectivity with Temporal Cloud with these steps:

1. Open the AWS console with the region you want to use to establish the PrivateLink.
2. Search for "VPC" in _Services_ and select the option.

   ![AWS console showing services, features, resources](/img/cloud/privatelink/aws-console.png)
3. Select _Virtual private cloud_ > _Endpoints_ from the left menu bar.
4. Click the _Create endpoint_ button to the right of the _Actions_ pulldown menu.
5. Under _Type_ category, select _Endpoint services that use NLBs and GWLBs_.
   This option lets you find services shared with you by service name.
6. Under _Service settings_, fill in the _Service name_ with the PrivateLink Service Name for the region you’re trying to connect from:

:::tip

PrivateLink endpoint services are regional.
Individual Namespaces do not use separate services.

:::

<JsonTable filename="/json/privatelink_aws.json" />

7. Confirm your service by clicking on the _Verify service_ button. AWS should respond "Service name verified."

   ![The service name field is filled out and the Verify service button is shown](/img/cloud/privatelink/service-settings.png)
8. Select the VPC and subnets to peer with the Temporal Cloud service endpoint.
9. Select the security group that will control traffic sources for this VPC endpoint.
   The security group must accept TCP ingress traffic to port 7233 for gRPC communication with Temporal Cloud.
10. Click the _Create endpoint_ button at the bottom of the screen.
    If successful, AWS reports "Successfully created VPC endpoint." and lists the new endpoint.
    The new endpoint appears in the Endpoints list, along with its ID.

    ![The created endpoint appears in the Endpoints list](/img/cloud/privatelink/endpoint-created.png)
11. Click on the VPC endpoint ID in the Endpoints list to check its status.
    Wait for the status to be “Available”.
    This can take up to 10 minutes.
12. Once the status is "Available", the AWS PrivateLink is ready for use.

:::caution
You still need to set up private DNS or override client configuration for your clients to actually use the new PrivateLink connection to connect to Temporal Cloud.

See [configure private DNS for AWS PrivateLink](#configuring-private-dns-for-aws-privatelink)
:::

    ![Highlighted DNS names section shows your hostname](/img/cloud/privatelink/details.png)

## Configuring Private DNS for AWS PrivateLink

### Why configure private DNS?

When you connect to Temporal Cloud through AWS PrivateLink you normally must:

1. **Point your SDKs/Workers at the PrivateLink DNS name** for the VPC Endpoint (e.g., `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com`), **and**
2. **Override the Server Name Indicator (SNI)** so that the TLS handshake still presents the public Temporal Cloud hostname (e.g., `my-namespace.my-account.tmprl.cloud`).

By creating a Route 53 **private hosted zone (PHZ)** that maps the public Temporal Cloud hostname (or region hostname) to your VPC Endpoint, you can:

- Keep using the standard Temporal Cloud hostnames in code and configuration.
- Eliminate the need to set a custom SNI override.
- Make future Endpoint rotations transparent—only the PHZ record changes.

This approach is **optional**; Temporal Cloud works without it. It simply streamlines configuration and operations. If you cannot use private DNS, refer to [our guide for updating the server and TLS settings on your clients](/cloud/connectivity#update-dns-or-clients-to-use-private-connectivity).

### Prerequisites

| Requirement                                           | Notes                                                                                                                              |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| AWS VPC with DNS resolution and DNS hostnames enabled | _VPC console → Edit DNS settings → enable both checkboxes._                                                                        |
| Interface VPC Endpoint for Temporal Cloud             | Subnets must be associated with the VPC and Security Group must allow TCP ingress traffic to port 7233 from the appropriate hosts. |
| Route 53 available in your AWS account                | You need permission to create Private Hosted Zones and records.                                                                    |
| Namespace details                                     | Needed to choose the correct override domain pattern below.                                                                        |

### Choose the override domain and endpoint

| Temporal Cloud setup                      | Use this PHZ domain                | Example                                         |
| ----------------------------------------- | ---------------------------------- | ----------------------------------------------- |
| Single-region namespace with mTLS auth    | `<account>.tmprl.cloud`            | `payments.abcde.tmprl.cloud` ↔ `vpce-...`       |
| Single-region namespace with API-key auth | `<cloud_provider>.api.temporal.io` | `us-east-1.aws.api.temporal.io` ↔ `vpce-...`    |
| Multi-region namespace                    | `region.tmprl.cloud`               | `aws-us-east-1.region.tmprl.cloud` ↔ `vpce-...` |

### Step-by-step instructions

#### 1. Collect your PrivateLink endpoint DNS name

```bash
aws ec2 describe-vpc-endpoints \
  --vpc-endpoint-ids $VPC_ENDPOINT_ID \
  --query "VpcEndpoints[0].DnsEntries[0].DnsName" \
  --output text